Sky map

sextant/skymap is a planisphere for the boat: the stars that are currently above the horizon, the lines that join them into the familiar constellation figures, and where the planets are. A screen draws it as a dome; on a night watch it answers "what is that bright one low in the south-east".

It is also the report closest to being a navigation aid: the stars a sextant sight uses are in it, with their compass bearing and altitude, which is enough to point the instrument.

Everything is expressed in horizontal coordinates — what you see from where you stand:

Field	Unit
altitude	degrees above the horizon; 0 = horizon, 90 = overhead
azimuth	compass bearing; 0 = North, 90 = East, 180 = South, 270 = West
magnitude	astronomical brightness; lower is brighter

Magnitude runs backwards, which is the usual trap. Sirius, the brightest star in the catalogue, is −1.44; the faintest stars an unaided eye picks out on a dark night are around +6; the full moon is about −12.7 and the sun about −26.7. A "maximum magnitude" of 5.0 therefore means dimmer than 5.0 is excluded.

The payload

{
  "data": {
    "stars": [
      { "id": 173, "altitude": 21.4, "azimuth": 176.3, "magnitude": -1.44, "name": "Sirius" }
    ],
    "constellations": [
      { "name": "Canis Major", "segments": [[188, 173], [173, 179]] }
    ],
    "planets": [
      { "name": "Jupiter", "altitude": 43.8, "azimuth": 128.5, "magnitude": -2.10 }
    ]
  },
  "metadata": { "rxDate": "2026-08-16T22:31:02Z", "expireAfterSec": 3600 }
}

stars

One entry per visible star. name is present only for stars that have a common name — most entries have none.

id is an internal identifier, not a catalogue number: the stars are numbered 1…1663 in the order they appear in the built-in catalogue. Sirius is 173, not its Hipparcos number. Its only purpose is to let the constellation segments name their endpoints, and it is stable only for a given build of the daemon — treat it as opaque and do not persist it.

altitude and azimuth are rounded to one decimal in the JSON, magnitude to two. That is a deliberate size measure: a full sky at magnitude 5 is several hundred stars, and full double precision on every one of them triples the payload for no visible benefit.

constellations

Each entry is a stick figure: a name — the full IAU constellation name — and a list of segments, where every segment is a pair of star ids to join with a straight line.

The ids refer to the stars array of the same message. A segment is only included when both of its endpoints are themselves in that array — so a constellation rising over the horizon appears with the lines it can currently draw and gains the rest as it climbs. A constellation with no drawable segment left is omitted entirely rather than published empty.

planets

Seven planets are computed: Mercury, Venus, Mars, Jupiter, Saturn, Uranus and Neptune. Each carries its position and its current visual magnitude, which for planets varies substantially with distance and phase.

Planets are filtered only on altitude, and only strictly above the horizon — --skymap-max-mag does not apply to them. Uranus and Neptune are not naked-eye objects and will still be listed whenever they are up, with magnitudes around +6 and +8. A display that draws everything in the planets array will draw two dots nobody on deck can see; filter on magnitude in the client if that matters.

What is filtered out

The two arrays use different rules:

Array	Altitude	Magnitude
stars	above −5°	brighter than --skymap-max-mag, default 5.0
planets	above 0°	not filtered

The −5° margin on stars is deliberate: an object about to rise is already in the payload, so a drawing does not pop in at the edge of the dome. Planets get no margin, so one can appear on the horizon between payloads.

Raising --skymap-max-mag adds fainter stars and grows the payload; lowering it gives a cleaner figure-only sky. The catalogue's own limit is the practical ceiling.

There is no daylight filter. The sky map is computed identically at noon and at midnight, and at noon it will faithfully report the stars that are above the horizon and invisible. A consumer that wants to blank the planisphere in daylight should use the sun's altitude from sextant/sun, which is published from the same recompute.

The catalogue

The star catalogue is built into the binary — 1663 stars, 695 constellation line segments and 88 constellations, generated from the HYG v3.7 database (Hipparcos, Yale Bright Star and Gliese, public domain) with constellation figures following the Stellarium "modern" sky culture. It is not a data file, needs no package, and cannot be replaced at runtime. The startup line confirms what was compiled in:

Skymap: Loaded 1663 stars, 695 lines, 88 constellations (built-in catalog)

Star positions are stored for epoch J2000.0 and precessed to the current date before being converted to horizontal coordinates, so the map is correct for the present decade rather than for the year 2000.

Update rate

The sky map is recomputed on the standard trigger — first fix, position drift beyond --recompute-drift-deg, or --recompute-interval-min elapsed — with no throttle of its own. At the default 15 minutes the whole sky has rotated about 3.75° between payloads, which is visible on a large display near the horizon.

Lowering --recompute-interval-min fixes it and also speeds up the sun, moon and magnetic reports, since they share the trigger. The tides report has its own floor and is unaffected.

Verifying it

mosquitto_sub -h 127.0.0.1 -t sextant/skymap -C 1 \
  | python3 -c 'import json,sys; d=json.load(sys.stdin)["data"]; \
      print(len(d["stars"]),"stars", len(d["constellations"]),"constellations", \
            [p["name"] for p in d["planets"]])'

With --verbose-skymap the daemon prints the same counts itself:

Skymap: Published skymap: 412 stars, 51 constellations, 4 planets

Zero stars with a valid position means either the position is in the payload but wrong, or --skymap-max-mag has been set below the brightest star in view. Zero constellations with a healthy star count means the visible stars are ones no figure uses.

Enable the report on its own with --report-skymap; the shipped unit passes --report-all.