Eclipse events need an ephemeris and a visibility model, not a date table #126

New issue

Open

opened 2026-09-04 23:36:11 +00:00 by claude-bot · 0 comments

claude-bot commented

2026-09-04 23:36:11 +00:00

Contributor

Why they did not go in with the rest

They are not computable from the current dependencies. astral gives sun and moon positions and phase — enough for full moons, which is why those are computed rather than tabulated — but it has no eclipse function. The same gap docs/troubleshooting.md already documents for solstices and equinoxes.

A date table would be the wrong shape here. Solstices are tabulated (ASTRONOMICAL_DATES, 2020–2035) and #61 exists precisely because that table silently runs out. Adding eclipses the same way would add a second thing to the horizon warning for a payoff that is smaller than it looks, because:

Only visible eclipses are worth lighting for. A total lunar eclipse over the Indian Ocean means nothing to a roofline in Texas. Visibility depends on the observer's latitude and longitude and on the eclipse's path — for a solar eclipse, whether it is total, partial or invisible varies over a few hundred kilometres. An event that fires for every eclipse worldwide would be wrong most of the time, and marking a "partial eclipse, 12% obscured, below the horizon" is worse than not marking it.

So the useful version needs both a source of eclipse circumstances and a per-observer visibility calculation, which is a real ephemeris dependency rather than a lookup.

What doing it properly looks like

Add an ephemeris library — skyfield is the usual choice and can compute both eclipse circumstances and local visibility. Note this is a heavier dependency than anything currently in the image, which #60 deliberately slimmed; worth weighing against the payoff of a handful of events a year.
Resolve eclipses against the configured LATITUDE / LONGITUDE, and only create an event when the eclipse is actually visible from there and above the horizon.
Carry magnitude, so a barely-partial eclipse can be filtered out or given a different scheme from a totality.
Built-in schemes: deep red for a lunar eclipse (the actual colour of one), a slow dim-and-return for a solar one.

The same dependency would also let the solstice and equinox tables be replaced by computation, closing #61's horizon warning for four of its six events — which may be the stronger argument for taking it on.

#20 — the delivered part: meteor showers, full moons, aurora
#61 — the lookup-table horizon this would otherwise extend
#60 — the image-size constraint an ephemeris dependency runs into

Split from #20, which delivered meteor showers, named full moons and the optional aurora layer. Eclipses were the remaining acceptance-criterion item and they are a materially different problem from the other two. ### Why they did not go in with the rest **They are not computable from the current dependencies.** `astral` gives sun and moon positions and phase — enough for full moons, which is why those are computed rather than tabulated — but it has no eclipse function. The same gap `docs/troubleshooting.md` already documents for solstices and equinoxes. **A date table would be the wrong shape here.** Solstices are tabulated (`ASTRONOMICAL_DATES`, 2020–2035) and #61 exists precisely because that table silently runs out. Adding eclipses the same way would add a second thing to the horizon warning for a payoff that is smaller than it looks, because: **Only *visible* eclipses are worth lighting for.** A total lunar eclipse over the Indian Ocean means nothing to a roofline in Texas. Visibility depends on the observer's latitude and longitude and on the eclipse's path — for a solar eclipse, whether it is total, partial or invisible varies over a few hundred kilometres. An event that fires for every eclipse worldwide would be wrong most of the time, and marking a "partial eclipse, 12% obscured, below the horizon" is worse than not marking it. So the useful version needs both a source of eclipse circumstances *and* a per-observer visibility calculation, which is a real ephemeris dependency rather than a lookup. ### What doing it properly looks like - Add an ephemeris library — `skyfield` is the usual choice and can compute both eclipse circumstances and local visibility. Note this is a heavier dependency than anything currently in the image, which #60 deliberately slimmed; worth weighing against the payoff of a handful of events a year. - Resolve eclipses against the configured `LATITUDE` / `LONGITUDE`, and only create an event when the eclipse is actually visible from there and above the horizon. - Carry magnitude, so a barely-partial eclipse can be filtered out or given a different scheme from a totality. - Built-in schemes: deep red for a lunar eclipse (the actual colour of one), a slow dim-and-return for a solar one. The same dependency would also let the solstice and equinox tables be replaced by computation, closing #61's horizon warning for four of its six events — which may be the stronger argument for taking it on. ### Related - #20 — the delivered part: meteor showers, full moons, aurora - #61 — the lookup-table horizon this would otherwise extend - #60 — the image-size constraint an ephemeris dependency runs into

claude-bot added the

area/backend

priority/low

type/feature

labels

2026-09-04 23:36:23 +00:00