MapsGL - Day/Night Overlay

The day/night overlay shades the map for civil, nautical, and astronomical twilight plus night. It follows the map timeline automatically, so the terminator moves as time advances.

Starting with MapsGL 1.10.0, you can set overall opacity, and the overlay stays in the top overlay slot (stack rank 1000). MapsGL re-pins it above other MapsGL layers whenever layers are added or moved, so weather fills do not cover the terminator.

Adding and removing

controller.on('load', () => {
    controller.addDayNightOverlay();
});

Pass opacity when you add it, or call addDayNightOverlay again to change it:

controller.addDayNightOverlay({ opacity: 0.7 });

Remove it with:

controller.removeDayNightOverlay();

The overlay uses the source and fill layer id mapsgl::daynight. Prefer addDayNightOverlay / removeDayNightOverlay over adding that layer yourself.

Options

Twilight bands

The overlay is four stacked semi-transparent fills. Each band is the region where solar elevation is at or below a threshold. Overlap darkens toward night:

You do not configure the bands. opacity scales the whole stack.

Timeline

The overlay reads controller.timeline.currentDate when added and rebuilds on each timeline advance. Rapid scrubbing and playback are coalesced to one geometry update per animation frame.

Set the timeline to the range you care about before or after adding the overlay — for a current terminator, start near now:

controller.timeline.setStartDateUsingRelativeTime('-6 hours');
controller.timeline.setEndDateUsingRelativeTime('+6 hours');
controller.addDayNightOverlay({ opacity: 0.85 });

Layer order

The overlay lives in the overlay slot with stack rank 1000, above debug and other chrome in that band. Adding satellite, radar, or other weather layers afterward does not cover it.

See layer ordering for slots and ranks, and the day/night overlay example for a live satellite + terminator map.