Nightfall

The problem

The line is live — the lights are not

A map of the Earth at night looks simple: city lights, and a line where the sun has set. The imagery is a public NASA tile service; the line is geometry. Getting both right is where the time goes. The newest city-lights composite is from 2016, the shape of night is a circle that a flat map bends into a wave, and sunset does not happen when the sun reaches the horizon.

Watch it work

Episode 10 — Nightfall (5:20)

One public source end to end: where the night imagery lives, the three details that cost the most time, and the map and globe it turns into.

What it covers

One source, three details, one map

• The source: NASA’s Global Imagery Browse Services (GIBS), a public tile service. Nightfall reads one layer from it, VIIRS Black Marble, built from the night-sensitive band of the VIIRS instrument on a NASA and NOAA weather satellite and served in the standard web map projection down to zoom level 8. Everything else on the map is math: the sun and the moon are placed with suncalc, an open source library, and no other data is downloaded.
• Detail one, the lights are not live: the service lists exactly two Black Marble composites, one for 2012 and one for 2016, so the lights on the map are the 2016 composite. The service also has a daily night image, but it shows clouds, seams between orbits and moonlit cloud tops; a composite removes those by combining many clear, moonless nights. Nightfall names the 2016 composite in its credit, and only the clock is live.
• Detail two, night is a circle: the sun’s height at any place is 90 degrees minus the distance to the point directly under the sun, so every place where the sun is below a given height lies inside one circle centered on the point opposite the sun — for full night, a radius of 72 degrees. Nightfall draws each boundary directly as a circle of 120 points. A search along each line of longitude fails near the equinoxes, when the night side touches neither pole.
• Detail three, sunset is not at zero: the air bends sunlight over the horizon by about half a degree, and the sun’s disc has a radius of about a quarter of a degree, so sunset happens when the center of the sun is 0.833 degrees below the horizon. A line drawn at zero sits about 90 kilometers on the wrong side — more than three minutes of sunset time at the equator. Nightfall draws its line at -0.833 degrees, and the legend says so.
• How it becomes a map: four bands stack over the lights — sunset to civil twilight, nautical twilight, astronomical twilight and full night — each a little darker toward the point opposite the sun; a gold marker shows the point under the sun and a white marker the moon’s, with the moon phase in the panel; in live mode the line moves once a minute, a scrubber moves the clock up to a day either way, a time-lapse adds ten minutes per frame, and a 3D globe is lit from the sun’s position, with 143 cities that glow once their sun has set.

What it does not do

• Not an almanac — Nightfall is a picture of the shape of night, not a source of exact local sunrise and sunset times.
• Not live lights — the city lights are the 2016 annual composite; only the day and night line follows the clock.
• Not terrain-aware — the line is computed for a smooth sphere, without mountains, valleys or local horizons.

Where the data comes from

Every source in the episode

• NASA GIBS (Global Imagery Browse Services) — earthdata.nasa.gov/eosdis/science-system-description/eosdis-components/gibs
• GIBS WMTS capabilities, Web Mercator — gibs.earthdata.nasa.gov/wmts/epsg3857/best/wmts.cgi?REQUEST=GetCapabilities
• GIBS API documentation — nasa-gibs.github.io/gibs-api-docs/
• NASA Black Marble — blackmarble.gsfc.nasa.gov/
• suncalc, sun and moon positions — github.com/mourner/suncalc
• Source sheet with every endpoint — allthingsspatial.io/pages/sources.html

The imagery is served by NASA GIBS, part of NASA’s Earth Science Data and Information System (ESDIS). The credit sits in the Nightfall footer and its About dialog.