Method & Accuracy

How Heliora Computes Its Numbers

Every time, angle and percentage in Heliora is computed from published data with published math, never typed in by hand. This page documents the method, the accuracy bounds and the known limitations, including a bug we shipped.

Sun & Moon Positions

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.

In the app, everything runs in your browser. No server does the math, so the numbers you see are computed live from your exact coordinates, not looked up from a table for the nearest city. Guide pages are built ahead of time with the same code.

The ΔT Correction

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 about 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 the live app and by every generator that builds guide pages, so the 3D view and the static guides quote the same contact times for the same spot.

Terrain: The Real Horizon

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 every ~200 m along each ray, with Earth-curvature and terrestrial refraction corrections (refraction coefficient 0.13). The sun and moon positions use astronomy-engine's standard atmospheric refraction. From a summit or clifftop the horizon can sit below 0°. Heliora never places it lower than the sea horizon for your eye height, which is about 0.3° down at 100 m and 0.85° at 833 m. 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, using the centre of the sun's disc. Moonrise and moonset in the app are recomputed the same way, using the centre of the moon's disc, and so are the moon pages' ridge times. The eclipse card's "Terrain takes the sun" time uses the sun's upper edge.

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 for the horizon, so ~110 m is the number we quote.

Summits are read finer. When you line the moon, sun or a planet up behind a named peak, its height is read at zoom level 12 (cells of roughly ~30 m), taking the highest cell within about one cell of the mapped summit. A ~110 m cell averages a narrow peak into its flanks: it read Half Dome, 2,693 m, as 2,458 m, and from the Glacier Point road that put the summit 3.3° too low, enough to list a moon "above the ridge" that was in fact behind the dome. At ~30 m the same summit reads 2,695 m. A line-up only counts when the moon's centre is above the summit itself, not just above the coarser horizon. The 3D view also draws the ridge within a few degrees of a chosen summit from the ~30 m data, so the summit marker sits on the drawn summit. Sun and moon rise and set times still use the ~110 m horizon.

A Bug We Shipped, and the Rule It Taught Us

Santa Ponça, August 2026

A user at a coastal spot in Santa Ponça, Mallorca, a good spot inside the path of totality, was told by Heliora that terrain blocked his view of the low eclipse sun. It didn't. The app was wrong, and this is why.

One elevation sample, taken just 200 m from his pin, averaged a nearby headland into the bay. It read 17.5 m of elevation where the truth is 0 m: open water. That single bad sample manufactured a 2.43° horizon in that direction, against a true horizon of about ~1.5°, and the difference was enough to flip the verdict from "clear view" to "blocked".

The root cause is leverage. A sample 200 m away sits inside a single ~110 m data cell, yet carries roughly 25× the angular influence of a distant one: 1 m of elevation error at 200 m tilts the horizon by 0.29°, while the same 1 m error at 5 km moves it just 0.011°. Sampling below the data's own resolution, exactly where errors hurt most, was the bug.

The fix: the ray-cast now refuses to sample closer than two DEM cells from the observer. We considered fetching higher-resolution tiles instead, and rejected it: it would have quadrupled the load on a free provider with no service guarantee on the busiest day of its year. Refusing to pretend the data is finer than it is was the honest fix. The same rule is enforced in the app and in the generator behind every baked guide page, so the two can't drift apart.

When Terrain Data Is Missing

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 a flat horizon. Visibility is unconfirmed. or Partial horizon — N% of terrain loaded. Visibility is unconfirmed.

Places & Clear-Sky Odds

Place searchGeoNames cities15000 dataset (CC BY 4.0): 33,534 cities bundled with the app, so settlement search works even when third-party services don't.
Cloud coverOpen-Meteo: its forecast for the next 16 days, and its ERA5 archive (20 years of cloud-cover history) for your pin and date.

Within the next 16 days the card shows Open-Meteo's forecast cloud cover for that hour, labelled Forecast (or Outlook beyond a week, where forecasts are much less reliable). For any other date it shows historical climatology, not a forecast: how often this hour of this date has been clear over the past 20 years at this spot. That is a planning odds figure, not a prediction of the weather you will get.

Accuracy Bounds & Known Limitations

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

  • Terrain-adjusted sunrise and sunset: usually within a few minutes. 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. When we re-ran our moon pages on ~30 m data, rise times moved by 0 to 2 minutes at four of the five sites and by 3 to 4 minutes at Half Dome, where a narrow granite summit sits close to the viewpoint. A steep, narrow ridge close to you is where the error is largest. These are comparisons between elevation datasets and against the published sunless periods of Rjukan and Viganella; we have not yet published a set of field-measured times.
  • 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. The sea is detected from cells at sea level.
  • 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.
  • Distant terrain is coarser. Rays are sampled at ~110 m pixels out to 30 km, then at ~0.5 km pixels out to 150 km, so a far range or island still counts from a summit. Anything beyond 150 km is not sampled, and narrow distant peaks can be softened.
  • The 3D view draws the sun and moon at their true angular size, about 0.5° across: a fingernail at arm's length. That is small on a phone, so you zoom the view in rather than having the discs enlarged; the eclipse preview zooms in on the sun for totality. The picture never feeds a computed number, and the eclipse card states the terrain-contact time so you never have to read it off the picture.

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

Understatement Is Policy

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 are shown to the nearest second, and they run slightly long. astronomy-engine uses a mean lunar radius with no mountain profile on the moon's edge, and against published values it overstates totality by about 2.5 to 5 seconds. Allow a few seconds of margin.
  • Unknown terrain is disclosed, never guessed. See above.
Open Heliora

Free. No account needed. Drop a pin and check the numbers yourself.

More: about Heliora · contact · city guides