src/core/horizon.js
The apparent horizon of a place from terrain elevation tiles: for every azimuth, the highest elevation angle of
the ground along that bearing, with the curvature of the Earth and terrestrial refraction. No DOM, no three.js:
the caller supplies getTile(z, x, y) (the browser decodes PNGs in src/sky/terrain.js, the test reads fixtures).
Data: "Terrarium" tiles of the Mapzen / Tilezen terrain tiles hosted in the AWS Open Data registry
(https://registry.opendata.aws/terrain-tiles/). Web-Mercator XYZ tiles of 256 x 256 pixels,
elevation [m] = R * 256 + G + B / 256 - 32768. The sources behind them (SRTM, 3DEP, EU-DEM, GMTED2010, ETOPO1,
...) and the attribution they require are in ATTRIBUTION below, from
https://github.com/tilezen/joerd/blob/master/docs/attribution.md.
Method
A ray leaves the observer along each azimuth on a great circle of a spherical Earth (radius 6371.0088 km; the
ellipsoid changes distances by at most 0.3%). Elevations are read bilinearly from a pyramid of zooms (BANDS):
fine tiles near the observer (zoom 13, 16 m pixels at 30 degrees latitude, out to 3 km), coarse ones far away,
so a profile needs some tens of tiles. The step is half a pixel of the zoom in use or 0.8% of the distance,
whichever is larger.
How far: the distance at which a sea-level horizon lies from the eye, plus 100 km for the mountains beyond it,
at least 150 km and at most 300 km (radiusFor): 150 km from the plains, 275 km from Kitt Peak (2100 m), 300 km
from Mauna Kea (4200 m), where the farther ground (Haleakala, 150 km from it) still shows.
The elevation angle of a point of height h at ground distance d seen from height h0 is that of a straight ray
over an Earth of radius Re = R / (1 - k): atan2((Re + h) cos(d / Re) - (Re + h0), (Re + h) sin(d / Re)).
k = 0.13 is the standard coefficient of terrestrial refraction (rays curve with 1/7.7 of the Earth's curvature);
it varies with the weather (0.1 to 0.2 by day, more over cold ground), which moves a ridge 100 km away by
about 0.03 deg.
The observer stands `eye` metres (2 by default; the Observe page lets it be set) above the terrain at the
place, or above `ground` when that is given, or above `elev` (the published elevation of an observatory) when
that is higher than the tiles' ground: observatory coordinates are rounded, and a point 50 m off a summit can sit
on its slope, where the summit itself makes a 20-degree horizon (Kitt Peak at the planner's 31.96333, -111.6:
the tiles give 2059 m, the site 2120 m). Sea floor in the tiles is raised to sea level (or to the
observer's level if that is below the sea). Beyond the end of the march the profile is never taken lower than
the dip of a sea-level horizon, -acos(Re / (Re + h0)).
What it is not: buildings and trees are not in the data (SRTM is a radar surface, so forest partly is), and the
nearest few pixels (30 m each at zoom 12 on the equator) cannot show a wall or a house next to the observer.
Checked in test/horizon.test.mjs against peaks of known position and height, and over the whole circle against an
independent implementation in Python (WGS84 geodesics, its own PNG decoding and sampling; test/data/terrain/full/).Import: import { … } from './src/core/horizon.js' — no DOM, runs in Node and the browser.
EARTH_RADIUS_M
const EARTH_RADIUS_MNo description in the source.
TILE_SIZE
const TILE_SIZENo description in the source.
TILE_URL
const TILE_URLNo description in the source.
terrariumElevation
const terrariumElevationElevation in metres of a Terrarium pixel.
BANDS
const BANDSZoom pyramid: [zoom, used out to this ground distance in metres]; a profile stops at maxDist (radiusFor).
BANDS_V1
const BANDS_V1The pyramid before 2026-11-15 (zoom 12 to 6 km, then 10, 9, 8 to 150 km), for comparisons.
radiusFor
const radiusForHow far a profile marches for an eye at height h0 metres above sea level: the distance of the sea horizon sqrt(2 Re h0) (Re with refraction) plus 100 km, within 150 to 300 km.
bandsFor
const bandsForThe pyramid for a latitude: Mercator pixels shrink with cos(latitude), so beyond 60 degrees one zoom less (two beyond 75.5) gives the same ground resolution with a quarter of the tiles.
DEFAULTS
const DEFAULTSNo description in the source.
ATTRIBUTION
const ATTRIBUTIONNo description in the source.
tileXY
function tileXY(lat, lon, z)Fractional Web-Mercator tile coordinates of a latitude and longitude in degrees at zoom z.
pixelSize
const pixelSizeGround size in metres of a pixel at zoom z and latitude (degrees).
destination
function destination(lat, lon, az, dist)The point reached from (lat, lon) after dist metres along the great circle of initial azimuth az (degrees).
elevationAngle
function elevationAngle(h0, h, d, k = 0.13)Apparent elevation angle (degrees) of a point of height h at ground distance d from an eye at height h0 (metres).
tileKey
const tileKeyNo description in the source.
tilesNeeded
function tilesNeeded(lat, lon, opts = {})The tiles a profile needs: [[z, x, y], ...], nearest zoom first.
horizonFromTiles
function horizonFromTiles(lat, lon, tiles, opts = {})The horizon profile. tiles: Map(tileKey(z, x, y) -> Float32Array or Int16Array of 256 * 256 elevations in metres,
row by row from the north-west corner); a missing tile is skipped and counted.
Returns { lat, lon, step, azFrom, n, alt: Float32Array (degrees, apparent), dist: Float32Array (m, to the point
that makes the horizon), elev: Float32Array (its elevation, m), ground: elevation at the observer (m),
eye: height of the eye (m), samples, missing: number of samples that fell on a missing tile }.elevationAt
function elevationAt(lat, lon, z, data)Elevation (m) at a place from one tile's elevations (bilinear), or NaN.
horizonProfile
function async horizonProfile(lat, lon, getTile, opts = {})Fetch what is needed and compute the profile. getTile(z, x, y) resolves to the elevations of a tile (see horizonFromTiles) or rejects / resolves to null when it cannot be had. onProgress(done, total) is optional. Unless opts.maxDist is given, the tile under the observer is read first and the march goes as far as radiusFor(its height + eye). Rejects only when no tile at all could be loaded.
horizonAt
function horizonAt(profile, azDeg)Horizon altitude in degrees at an azimuth in degrees, linearly between the samples of a full-circle profile.