Skyhunter

Skyhunter is the offline target-choosing and planning module. Find it in the left nav as Skyhunter. Its whole reason for existing: pick and plan tonight's targets without the internet — answering "what's well-placed right now, and where is it in the frame?" from bundled catalogs and local astronomy. This is the deliberate contrast with Sky Atlas, whose Aladin view needs the network to load tiles. The subtitle says it plainly: offline catalog · planets, asteroids & comets · tonight's visibility · satellite passes.

What it can find

• Offline deep-sky catalog — a bundled, magnitude-filtered slice of OpenNGC: ~3,919 objects (106 Messier), with type, magnitude and size. Search by name, Messier number (M8), NGC/IC designation, type or constellation. The catalog filter (all types) and an optional max mag narrow the list.
• Planets and the Moon — search Jupiter, Mars, Moon, etc. Their position and brightness are computed locally, right now, no internet. (The internal Sun position matches reference to 0.4 arcmin.)
• Asteroids — the brightest ~525 minor planets are bundled (Vesta, Ceres, Pallas, Juno…). They appear in search, in Tonight's Best, and on the finder chart with their current position and brightness (IAU H,G model).
• Comets — the current bright comets from the MPC, solved with an engine that handles the near-parabolic and hyperbolic orbits comets actually have. Note: predicted comet magnitudes are rough MPC estimates, often off by magnitudes — the detail view says so.
• Your own elements — the Paste custom elements box takes an MPC one-line comet (CometEls) or asteroid (MPCORB) record, or a plain labelled set (a, e, i, node, peri, M, epoch for an asteroid; q, e, i, node, peri, Tp for a comet), for anything not in the bundle. It's forgiving — paste a JPL/MPC element table with the usual synonyms (ecc, inc, Omega, w, Tp, dates as YYYY-MM-DD or a JD) and it reads it. Computed with the same offline engine and shown in the detail panel, ready to sequence just like a bundled object.

Type a name, Messier number (M8), NGC/IC designation, a planet (Jupiter), an asteroid (Vesta) or a comet (Lemmon) into the search box; the category dropdown and the optional max mag narrow it, and matches come back brightest-first.

Tonight's visibility

Select any object and Skyhunter computes, locally from your site, what you need to decide whether to shoot it tonight:

• the altitude curve over the whole night, with the dark window (sun below twilight) shaded, the moon's altitude drawn faintly alongside, the transit dotted in, and a "now" line marking the current moment. The curve is drawn noon-to-noon so tonight's darkness sits in the centre of the graph rather than falling off the edge;
• the transit altitude and time, with its azimuth;
• the observable window — when the object is above your altitude floor and in darkness — as a start–end span, hours, and peak altitude (or "not above N° during darkness");
• airmass and azimuth (with a compass direction) at any sampled time, so you can see when the target is lowest through the atmosphere;
• moon separation at transit and illumination (% lit).

Visibility needs your real site coordinates. With [site] unset (0,0), the panel tells you to set them in Settings → Site / Location — and the planning math is wrong until you do.

Moon-safe filters

When scheduler moon-avoidance is on, the detail view adds a Usable filters at transit row — two chips, Broadband and Narrowband — showing which filter classes the moon still permits for this target tonight (a struck-through chip means that class is washed out). The same BB / NB chips appear next to each row in the results list, and the Hide moon-washed checkbox above the list drops any target the moon ruins for every filter type — a fast way to see only what's actually shootable under tonight's moon. If moon avoidance is switched off in scheduler settings, the row says so.

Tonight's Best

The ★ Tonight's best button ranks the catalog (plus planets and small bodies, but never the Moon itself) by how well-placed each object is during tonight's dark window. The ranking is moon-aware: a bright, high moon docks the score of nearby targets, so a 76%-lit moon pushes its neighbours down and favours the dark side of the sky. Each row shows the target's peak altitude and moon separation for the night, and — when moon avoidance is on — the Broadband/Narrowband chips, so the Hide moon-washed checkbox works here too. The status line under the list summarises tonight's dark hours and how lit the moon is. Skyhunter opens straight to this ranking, so you see what's up tonight before you even search.

The finder chart

Every object's detail view draws an offline finder chart from the bundled catalogs — bright stars, nearby objects, and planets — with your camera's FOV box overlaid as a dashed rectangle, N up, E left. The FOV comes from the framing settings; the chart radius scales to the frame diagonal. This is framing that works with no internet — exactly the guarantee Aladin couldn't make.

Acting on a target

The detail view has three buttons:

• + Sequence target — drops the object straight into the sequence editor as a new target (RA/Dec filled in), switches you to the Sequence module, and confirms with a banner. If the sequence still has only its empty default target, this replaces it; otherwise it appends.
• Frame in Sky Atlas — hands the object to the Sky Atlas framing view.
• + Scheduler plan — jumps to the Schedule page and prefills the Add project form (name, RA, Dec) from this target, so you can pick filters and frames and add it to the multi-night scheduler. A note reminds you to finish the form.

For a moving body (planet, Moon, asteroid, comet, or custom elements), the detail view shows a ↻ moving — position computed now (snapshot) warning (with the "magnitude is an MPC estimate" caveat for comets), and both target buttons use the clean label and note the RA/Dec is a snapshot. Re-resolve the target before a later run — these bodies move, and coordinates captured now will be stale by the time the plan executes.

Satellite passes

The Satellite passes panel is a heads-up predictor, not a sequence target. A LEO satellite crosses the sky in minutes at degrees per second; a sidereal rig cannot image it. This tells you when the ISS (or any bright satellite) passes over your site — how high, which way (e.g. "NW→SE, peak 72°"), how bright, and whether it'll be sunlit.

It runs a real near-Earth SGP4 propagator (validated to nanometres against the standard test vectors) over cached TLEs, with Sun/Moon transit-candidate flags. Set a satellite (all bright, or ISS / 25544), a look-ahead in hours, a minimum elevation in degrees, and the visible only filter, then Predict. Geostationary / GPS-type orbits are flagged and skipped — they need a different model and don't make fast visible passes.

Refreshing the offline catalogs

The bundled catalogs live in starship/core/data/ (skyhunter_dso.csv, skyhunter_asteroids.csv, skyhunter_comets.csv, skyhunter_tle.txt). The moving-body data goes stale — asteroid/comet elements in a few weeks, satellite TLEs in a few days — so Skyhunter watches their age for you. When anything is past its freshness window (or was never fetched), a yellow banner appears at the top of the page naming which catalog is stale, how old it is, and the exact script to re-run. Refresh from a machine with internet using the scripts in scripts/:

• build_skyhunter_asteroids.py — rebuild the asteroid bundle (JPL SBDB, or a local MPCORB.DAT for an all-MPC pipeline).
• fetch_skyhunter_comets.py — pull the current bright comets from the MPC.
• fetch_skyhunter_tle.py — refresh the satellite TLEs used by the pass predictor.

The deep-sky catalog is static and never counts as stale (build_skyhunter_catalog.py rebuilds it, rarely needed).

Endpoints

For reference, the module is served by /api/skyhunter/search (catalog search), /api/skyhunter/object (detail + visibility + moon-safe filters), /api/skyhunter/field (finder-chart field), /api/skyhunter/tonight (Tonight's Best), /api/skyhunter/custom (compute pasted elements, POST), /api/skyhunter/passes (satellite passes), and /api/skyhunter/catalog-status (age + staleness of the refreshable catalogs, which drives the yellow banner).

Notes

• It's renameable. The display name lives in one place (DISPLAY_NAME in core/skyhunter/__init__.py) — rebrand it to Object Hunter, Plan Commander, or whatever you like.
• Skyhunter is a planner, not a full planetarium. It answers "what should I shoot and where is it in the frame?" offline; the deep Aladin sky survey stays in Sky Atlas.
• The astronomy was validated end-to-end: M42's transit altitude, the Sun at solstice, the Moon's motion and phase, and the small-body engine against JPL Horizons and the canonical SGP4 vectors.