Skip to content

src/core/horizon.js ​

text
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 ​

js
const EARTH_RADIUS_M

No description in the source.

TILE_SIZE ​

js
const TILE_SIZE

No description in the source.

TILE_URL ​

js
const TILE_URL

No description in the source.

terrariumElevation ​

js
const terrariumElevation

Elevation in metres of a Terrarium pixel.

BANDS ​

js
const BANDS

Zoom pyramid: [zoom, used out to this ground distance in metres]; a profile stops at maxDist (radiusFor).

BANDS_V1 ​

js
const BANDS_V1

The pyramid before 2026-11-15 (zoom 12 to 6 km, then 10, 9, 8 to 150 km), for comparisons.

radiusFor ​

js
const radiusFor

How 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 ​

js
const bandsFor

The 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 ​

js
const DEFAULTS

No description in the source.

ATTRIBUTION ​

js
const ATTRIBUTION

No description in the source.

tileXY ​

js
function tileXY(lat, lon, z)

Fractional Web-Mercator tile coordinates of a latitude and longitude in degrees at zoom z.

pixelSize ​

js
const pixelSize

Ground size in metres of a pixel at zoom z and latitude (degrees).

destination ​

js
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 ​

js
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 ​

js
const tileKey

No description in the source.

tilesNeeded ​

js
function tilesNeeded(lat, lon, opts = {})

The tiles a profile needs: [[z, x, y], ...], nearest zoom first.

horizonFromTiles ​

js
function horizonFromTiles(lat, lon, tiles, opts = {})
text
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 ​

js
function elevationAt(lat, lon, z, data)

Elevation (m) at a place from one tile's elevations (bilinear), or NaN.

horizonProfile ​

js
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 ​

js
function horizonAt(profile, azDeg)

Horizon altitude in degrees at an azimuth in degrees, linearly between the samples of a full-circle profile.

MIT licensed · Kyle A. Pearson