How Heliora Computes Its Numbers

Sun and moon positions, rise and set times, twilight phases, and local eclipse circumstances all come from astronomy-engine, an open-source astronomy library (MIT licence). It computes positions to within ±1 arcminute — about 1/30th of the sun's apparent diameter.

Everything runs in your browser. There is no server doing the math, so the numbers you see are computed live from your exact coordinates, not looked up from a table for the nearest city.

Earth's rotation is slowing irregularly, and eclipse predictions depend on a correction called ΔT (delta-T) that no formula predicts perfectly — it has to be measured. astronomy-engine's default is the Espenak–Meeus ΔT model, which extrapolates 75.4 seconds for 2026. The observed value is around ~69.2 seconds.

Left uncorrected, that gap would put every 2026 eclipse contact time about 6 seconds early. Heliora pins ΔT to the observed value in one shared module, imported by both the live app and the generator that builds every city guide page — so the interactive 3D view and the static guides can never quote different contact times for the same spot.

The terrain horizon — when a mountain actually takes the sun — is built from AWS Terrain Tiles, a free public elevation dataset in Terrarium encoding. Your browser downloads the raw tiles and decodes each pixel's elevation itself:

elevation = (r × 256 + g + b / 256) − 32768

The decoded value is clamped at 0. That matters because Terrarium carries real bathymetry — ocean depth — and without the clamp, a sight line over the Mediterranean would "see" the seabed 800 m below the surface instead of the water.

From your pin, Heliora casts 360 rays outward, one per degree of compass bearing, sampling elevation along each ray with an Earth-curvature correction. The result is a full horizon profile: for every direction, the angle at which terrain ends and sky begins. Sunrise and sunset are then recomputed against that profile instead of a flat mathematical horizon.

An honest number about resolution: Heliora samples 256-pixel tiles at zoom level 10, which works out to ground pixels of roughly ~110 m at Spanish latitudes. The source datasets underneath (NASA SRTM, USGS 3DEP and others) are finer — around 30 m — but ~110 m is what Heliora actually reads, so ~110 m is the number we quote.

Elevation tiles come from a free provider, and free providers have bad days. When a tile fails to load, Heliora treats that elevation as unknown — never as sea level. The distinction matters: on a rate-limited day, treating failed tiles as zero would confidently paint a flat ocean horizon around a mountain valley.

Unknown terrain is disclosed, never guessed. The UI says so verbatim: Terrain unavailable — showing flat horizon or Partial horizon — N% of terrain data loaded.

The clear-sky number is historical climatology, explicitly not a forecast. It answers "how often has this hour of this date been clear over the past 20 years at this spot?" — a planning odds figure, not a prediction of the weather you will get.

Stated plainly, because a tool you trust is a tool that tells you where it's weak:

• Terrain-adjusted sunrise/sunset: ~1–3 minutes typical accuracy. The astronomical position is good to ±1 arcminute; the uncertainty comes from the elevation data and where exactly a ridge line falls within a ~110 m pixel.
• Lakes and rivers render as land. Water detection is sea-level-only. Lake Geneva sits at 372 m and draws as land; rivers narrower than a DEM pixel disappear into their banks. Sea coastlines are handled correctly.
• Features smaller than ~110 m can be missed or smeared. A narrow rock pinnacle, a building, or a thin gap in a ridge may not appear in the horizon profile at all.
• The 3D view draws the sun and moon ~7× their true angular size by default, so they stay visible and legible on screen. At true scale the sun is about 0.5° across — a fingernail at arm's length — and nearly invisible on a phone. A desktop "True size" toggle shows the honest discs. Either way, displayed times always use true geometry: the drawing scale never touches a computed number, and the eclipse card states the computed terrain-contact time explicitly so you never have to read it off the picture.

If a number matters to your plans — an eclipse contact time, a terrain verdict for a specific spot — treat these bounds as part of the answer.

Where rounding is unavoidable, Heliora rounds in the direction that can't oversell:

• A non-total eclipse never displays 100% obscuration. Madrid in 2026 is ~99.95% obscured — which ordinary rounding would show as 100%, and a reader would conclude they'll see totality there. They won't. Heliora renders it as 99.99%, rounded down, because understating by a fraction is harmless and overstating sends someone to the wrong town.
• Totality durations round down. A duration you read in Heliora is one you will get at least that much of.
• Unknown terrain is disclosed, never guessed — see above.