zenith: Automated Celestial Navigation

zenith answers one question without GPS: where am I on Earth? Given a photograph of the night sky, an IMU gravity vector, and a UTC timestamp, it returns latitude, longitude, and a rigorous 2-sigma uncertainty ellipse.

The engine is validated end to end against an independent reference implementation (astropy) using the real Yale Bright Star Catalog: position fixes land within 0.1 to 0.2 nautical miles of truth on noise-free synthetic imagery, and within 5 nautical miles under realistic sensor noise (3 arcminutes of star-position error plus IMU tilt noise).

How it works

This is automated celestial navigation: the same idea sailors used with a sextant and star charts for centuries, now done by a computer from a single photograph in a fraction of a second.

Consider the night sky is a ceiling covered in dots, and every dot has a known name and a known place. If you can work out which dots you photographed and which way the camera was pointing, you can work backwards to the one spot on Earth where the sky would look exactly like that. Zenith needs only three things to do it: the photo, which way is down (gravity, from an IMU), and the exact time.

It runs in five steps:

1. Find the dots. Pinpoint each star in the photo to within a fraction of a pixel.
2. Name the dots. Measure the angles between stars (those stay the same however the camera is tilted) and look the pattern up in a catalogue of about 9,100 real stars. If the field is ambiguous, Zenith refuses to guess and raises an error rather than risk a wrong fix.
3. Find where the camera pointed. Turn the named stars into the camera's orientation in the sky.
4. Take a first position. Gravity tells it which way is straight up, and the star directly overhead is, in effect, your latitude and longitude. This falls straight out of a single frame, with no prior position and no dead reckoning.
5. Refine and report. Polish the fix and report a 2-sigma uncertainty ellipse: "you are within this small patch".

Steps 2 and 3 are the heart of it: the angles between stars stay fixed however the camera is aimed, so a triangle of dots identifies the stars, and a single rotation then recovers where the camera pointed.

For a runnable, illustrated walkthrough of these two steps (with diagrams and animations), see examples/how-it-works.ipynb.

It also works by day. Daytime sky brightness is scattered sunlight, and scattering falls off steeply toward longer wavelengths, so in the short-wave infrared (about 0.9 to 1.7 micron) the sky background drops away while the brightest stars still shine. Zenith ships a separate infrared catalogue (real 2MASS J/H photometry) and a solar-disc detector, so a SWIR camera can fix position in daylight, resolving within about a nautical mile at the validation sites. The Sun itself can be added as an extra sight: a known body needs no identification, only an ephemeris, and it contributes one more line of position that strengthens a star fix or fills in when stars are sparse. See docs/how-it-works.md for the reasoning and docs/algorithms.md for the equations.

The deeper story lives in the docs. For the conceptual walkthrough (why each stage is built the way it is, the arcminute-level accuracy budget, and the refusal properties that make a fix with errors), see docs/how-it-works.md. For the full equations, the formal method names (subpixel centroiding, the k-vector lost-in-space match, Wahba's problem solved by SVD, the Marcq St. Hilaire intercept method), and code references, see docs/algorithms.md. For carrying a fix through motion on a moving platform (the orientation MEKF and the position INS Kalman filter, with the maths and worked examples), see docs/fusion.md. For the camera-mount and optics study (which camera, lens, and catalogue to carry, and what an end-to-end flight reveals that a single frame cannot), see docs/camera-and-optics.md.

Documentation

Start here and read in order; each page builds on the one before.

1. This README: the public API, the validation results, the browser demo, and the desktop app.
2. docs/how-it-works.md: the conceptual walkthrough, stage by stage, with the accuracy budget and the refusal properties.
3. docs/algorithms.md: every equation, with the code excerpt that evaluates it and the embedded catalogue format.
4. docs/fusion.md: carrying a fix through motion, the orientation MEKF and the position PosKf, with maths and worked examples.
5. docs/camera-and-optics.md: the camera-mount and optics trade study (which camera, lens, and catalogue to carry).
6. docs/real-sky-validation.md: the attitude pipeline validated on real night-sky data (the EBS-EKF public dataset), method and caveats.
7. crates/zenith-autopilot/README.md: plugging the engine into an ArduPilot flight stack, the GPS_INPUT contract, and the live SITL demo.
8. docs/python-api.md: the full Python API reference.

For runnable walkthroughs see the notebooks under examples/ (quickstart.ipynb, how-it-works.ipynb, camera-system-trade-study.ipynb).

Architecture

Cargo workspaces are used to decouple the main resolver engine from other aspects of the system.

Project structure

zenith/
├── Cargo.toml                  # workspace
├── pyproject.toml              # Python package metadata (maturin)
├── crates/
│   ├── zenith-core/            # pure Rust engine, pixels to fix (MSRV 1.82)
│   ├── zenith-fusion/          # MEKF + PosKf Kalman filters for motion
│   ├── zenith-hal/             # sensor-source traits + record/replay codec
│   ├── zenith-autopilot/       # ArduPilot companion daemon (GPS_INPUT + MEKF)
│   ├── zenith-camera/          # real camera drivers (GenICam/Aravis, V4L2)
│   ├── zenith-sim/             # motion/mount/optics simulation study
│   ├── zenith-py/              # PyO3 bindings (lib name: zenith)
│   ├── zenith-wasm/            # wasm-bindgen bindings + scene synthesis
│   └── zenith-desktop/         # native Tauri desktop app (reuses web UI)
├── python/
│   ├── zenith/
│   │   ├── pipeline/           # Polars BSC5 builder + binary writers
│   │   └── simulate/           # astropy sky renderer + demo plots
│   └── tests/                  # bindings, pipeline, simulate, e2e suites
├── scripts/                    # node wasm/globe tests + howitworks figure generator
├── web/                        # browser tactical demo (no bundler)
├── packaging/                  # demo bundle README + macOS launcher
├── docs/images/                # rendered demonstration plots
├── data/                       # generated artefacts (gitignored)
└── .github/workflows/ci-cd.yml # fmt + clippy + cargo test + pytest + wasm

The embedded star catalog

The pipeline produces two compact little-endian artefacts consumed by the Rust core (formats documented in crates/zenith-core/src/catalog.rs):

• catalog.bin: all ~9,100 BSC5 stars (HR number, magnitude, J2000 RA/Dec, precomputed unit vector), 48 bytes per star.
• pairs.bin: every pair of bright stars (magnitude 4.5 or brighter, about 30,000 pairs within 30 degrees) sorted by angular separation, ready for binary search. Matching only ever needs bright stars; sight reduction uses the full table.

For daytime SWIR fixes the pipeline also writes catalog_ir.bin and pairs_ir.bin in the identical formats, built from real 2MASS J/H photometry cross-matched to the BSC5, with a brighter pair-index cut (J 4.0 or brighter).

There is no database engine at runtime. Polars does the heavy lifting offline, and the derived-column stage runs through the Polars lazy API, so it can execute on an NVIDIA GPU via the RAPIDS cudf-polars engine (parse(raw, engine="gpu")). At BSC5 scale that is architectural headroom for future Tycho-2 or Gaia subsets rather than a present-day speedup.

Roadmap

Delivered beyond the core engine: the motion-fusion filters and their study (docs/fusion.md), the mount and optics trade study (docs/camera-and-optics.md), real-sky attitude validation (docs/real-sky-validation.md), the ArduPilot integration (SITL-proven, see Navigate on it), a camera-agnostic hardware seam (any camera satisfying the zenith-hal backend contract plugs into the daemon, with GenICam and V4L2 drivers proven against protocol-true test rigs in CI), and the first real-photon position fixes: frames from the public LenghuSky-8 all-sky dataset resolve to 35-67 nm of the surveyed site on two independent nights (93 and 110 matched stars), via mesh-background detection and a calibrated degree-9 fisheye model (issues #39, #40).

In progress and next, tracked as GitHub issues:

• Real-sky position validation from a surveyed ground site on our own hardware, closing the loop from camera to fix end to end (#26).
• Replacing the assumed per-star measurement noise with a value measured on real hardware, and tightening the reported uncertainty (#36).
• The physical deployment path: companion-computer link, mounting, and power on a real airframe (#35).
• Celestial yaw injection (a drift-free, magnetometer-free heading) and a real camera/IMU sensor backend (#31).

Further out: cloud-masked degraded-sky operation, and a Gaia-scale catalogue with quad-code hashing for the lost-in-space match.

Quickstart

Install and use

The distribution is zenith-fixer; the import is zenith. The star catalogue ships inside the wheel, so a fix needs no download or build step.

pip install "zenith-fixer[viz]"   # [viz] adds matplotlib, plotly and astropy for the plots

import zenith

catalog = zenith.bundled_catalog()  # bundled with the wheel; no external files
fix = zenith.resolve_fix(
    image,                      # numpy uint16 array (uint8 also accepted), shape (height, width)
    1500.0, 512.0, 512.0,       # focal length and principal point, pixels
    (ux, uy, uz),               # unit vector toward the zenith, camera frame
    (2026, 1, 15, 2, 0, 0.0),   # UTC
    catalog,
    sigma_arcmin=1.0,           # assumed 1-sigma altitude noise
)
print(fix.latitude_deg, fix.longitude_deg)
print(fix.ellipse_2sigma_nm)    # (semi-major nm, semi-minor nm, orientation deg)
print(fix.matched_hr_ids)       # which catalog stars were identified

The full Python API is documented in docs/python-api.md. For an end-to-end walkthrough with plots (synthesised sky, all-sky skymap, an interactive globe of the fix, and the uncertainty ellipse), see examples/quickstart.ipynb. For a conceptual companion that explains how the matcher names the dots and how Wahba's problem recovers the camera's orientation (with diagrams and animations), see examples/how-it-works.ipynb. For the executive trade study that recommends what camera and mount to carry (the mount and optics findings, a hardware shortlist, and what is ready for a field test), see examples/camera-system-trade-study.ipynb.

Develop from source

Requirements: Rust 1.82+, Python 3.10+, uv.

uv sync   # builds the extension and installs the full dev toolchain
# after changing Rust, rebuild the extension into the venv:
.venv/bin/maturin develop --manifest-path crates/zenith-py/Cargo.toml

# the catalogue is vendored under python/zenith/data; to rebuild it from the
# real BSC5/2MASS sources and refresh that copy:
make pkg-data

# run the tests
cargo test --workspace --exclude zenith-desktop
.venv/bin/pytest python/tests/

Validation

The synthetic test harness places stars with astropy (its own precession, aberration, and refraction models), renders them onto a sensor frame with Gaussian point-spread functions, and perturbs the IMU vector. Because the generator shares no transform code with the engine, the acceptance tests are a genuine cross-implementation check:

The covariance-calibration row is a true elliptical (Mahalanobis) containment test: each noisy fix's offset from truth is projected onto the principal axes of its own 2-sigma ellipse and counted inside when it lands within the ellipse, not within a circle of the semi-major radius. For a well-calibrated 2D Gaussian the expected containment is 1 - exp(-2) = 0.865; the harness measures about 0.92 over at least 100 deterministic realisations (the covariance runs slightly conservative), and the test asserts the fraction stays in the band 0.70 to 0.97.

The matcher's refusal property is tested directly: a congruent star pattern duplicated on the opposite side of the sky must raise MatchAmbiguous rather than guess, while catalogued close doubles (Alnitak, Mintaka) must not trigger false ambiguity.

Real photons, not just synthetic ones. The attitude pipeline (centroiding, star identification, Wahba attitude) is additionally validated on real night-sky data: run blind over all 15 science tracks of the public EBS-EKF release with an independent per-collect lens calibration, zenith agrees with the authors' astrometry.net solutions to a median boresight of 73 arcseconds, in the neighbourhood of their own ~100 arcsecond headline. See docs/real-sky-validation.md for the method, the gating, and the caveats. This validates attitude only; the full real-sky lat/lon campaign is tracked as issue #26.

Navigate on it: ArduPilot integration

The engine plugs into a stock ArduPilot flight stack with no firmware change: a companion daemon (zenith-autopilot) resolves fixes from a sensor stream and sends them as MAVLink GPS_INPUT, so the autopilot's EKF3 fuses starlight exactly as it would a GNSS receiver. This is proven live against ArduPilot SITL, captured output:

STATUS: GPS 1: detected MAV
STATUS: EKF3 IMU0 origin set
STATUS: EKF3 IMU0 is using GPS
STATUS: EKF3 IMU1 is using GPS
engine fixes produced and sent: 264
test engine_fixes_drive_sitl_to_convergence ... ok

Every fix carries its own solve-derived 1-sigma accuracy in GPS_INPUT.horiz_accuracy, so EKF3 weights celestial fixes honestly, and a refused frame sends nothing (the EKF coasts, as through a GPS dropout). An onboard orientation MEKF fuses gyro samples with accepted star fixes to keep the solve's up vector honest through manoeuvres, behind conservative trust gates. The daemon compiles to a single static aarch64-musl binary (~2.5 MB stripped, star catalogue embedded) that drops onto a Raspberry Pi or i.MX class companion computer. Demo recipe, SITL parameters, and the full contract: crates/zenith-autopilot/README.md.

Demonstration plots

Generate with .venv/bin/python -m zenith.simulate.covariance_plot and .venv/bin/python -m zenith.simulate.zero_crossing.

Sight geometry drives uncertainty. Two stars separated by only 30 degrees of azimuth give nearly parallel lines of position; the 2-sigma ellipse (computed by the Rust engine, not re-derived in Python) stretches across the weakly constrained direction:

Shoot on the roll. At sea the camera cannot be stabilised, but it can be triggered. Sampling the IMU at high rate and firing the shutter as the hull rolls through zero removes the platform tilt from the measurement; the zero-crossing fixes cluster on the true position while randomly timed exposures smear with the roll angle:

Browser demo

The engine compiles to WebAssembly unchanged and ships with a fully client-side tactical display: pick a position, time, and noise level; the page synthesises the night sky that would be photographed there from the real BSC5 catalog, identifies the stars, and resolves the fix in the browser. No server-side computation is involved. Alongside the sky view, a 3D orthographic globe panel renders real Natural Earth coastlines that you can drag to rotate, with a pulsing pinpoint that recentres on every resolved fix.

The demo defaults to the fisheye all-sky lens; the LENS toggle also offers PINHOLE, and the projection is selectable from the fisheye_fov_deg parameter on resolve_fix in Python and on the WASM bindings. An all-sky field spreads the stars across the whole sky, which strengthens the fix geometry and yields a noticeably tighter uncertainty ellipse on a noiseless single frame (the dilution-of-precision picture), and it gives the wide field of view a daytime fix needs, at the cost of lower per-star angular resolution. At a realistic 16-bit sensor depth the two lenses fix equally well through real motion and centroiding noise, so that single-frame star-spread edge does not open a measurable end-to-end accuracy gap. An earlier 8-bit render had made the pinhole look the more precise lens, but that was a dynamic-range artefact (the 8-bit sensor saturated the bright stars and buried the faint ones), corrected once the study was regenerated at the depth a real star camera delivers; see camera-and-optics.md (sub-project G). The demo uses the ideal equidistant projection; a real fisheye lens uses the calibrated degree-9 distortion model (k1..k4 on resolve_fix), which is what the LenghuSky-8 real-photon fixes required.

Run it

A Makefile wraps the build and serve steps. With the toolchain installed (see Quickstart):

make serve
# then open http://localhost:8123/web/

make serve rebuilds the WebAssembly package and the catalog artefacts when they are missing, then serves the repository root. In the page, RESOLVE FIX runs a fix, RANDOM SKY picks a random position and time, and the LENS toggle switches between the pinhole and fisheye all-sky models.

The equivalent manual steps:

.venv/bin/python -m zenith.pipeline   # catalog + coastline artefacts (one-time)
wasm-pack build crates/zenith-wasm --target web --out-dir ../../web/pkg
.venv/bin/python -m http.server 8123  # then visit http://localhost:8123/web/

Share it

To give the demo to someone with no toolchain, package it into one self-contained zip:

make bundle
# writes dist/zenith-demo.zip

The zip holds the web app, the compiled WebAssembly engine, the real catalog and coastline data, a plain-English README, and a double-click launcher for macOS. The recipient unzips it and runs a local static server (the bundled instructions cover macOS, Linux, and Windows); nothing is installed and nothing leaves their machine. Because the demo is fully static and client-side, it can equally be hosted on any static host (GitHub Pages, Netlify) and shared as a link; the host only needs to serve .wasm with the application/wasm MIME type, which those services do by default.

The same engine path is exercised headlessly by the smoke test:

make test          # full suite, including the wasm smoke test
# or just the wasm smoke test:
wasm-pack build crates/zenith-wasm --target nodejs --out-dir ../../build/wasm-node
node scripts/wasm_smoke.mjs

References

• Yale Bright Star Catalogue, 5th revised edition: http://tdc-www.harvard.edu/catalogs/bsc5.html
• Bennett, G. G. (1982). The calculation of astronomical refraction in marine navigation. Journal of Navigation, 35(2).
• Markley, F. L. (1988). Attitude determination using vector observations and the singular value decomposition. Journal of the Astronautical Sciences, 36(3).
• Mortari, D. et al. (2004). The pyramid star identification technique. Navigation, 51(3).
• RAPIDS cuDF Polars GPU engine: https://docs.rapids.ai/api/cudf/stable/cudf_polars/