Drawing the Real Night Sky in a Browser

How Asterarium Works

Asterarium is a planetarium that runs in a browser. Choose a place on Earth and a moment in time, and it draws the sky of that place at that moment: the arrangement of the stars, the positions of the Sun, Moon and planets, and the brightness of the sky itself all come from real catalogues and astronomical calculation.

This article explains how it works, for developers. It starts from one constraint, a static site with no server-side code at all (no program runs on a server when a page is opened; what is served is only the files finished at build time), then follows what was decided, why, and how, across the ten sections listed below: from the big picture at the start to the design principles that run through all of them at the end.

Each section stands on its own, which is why a few premises are restated briefly from one section to the next. Jump to whichever one interests you from the table of contents. Within each section, astronomy and 3D-rendering terms carry notes. What the constraint cost, and what it bought, is set out at the end of the closing section, "Design Principles, in Summary".

The Big Picture: No Server-Side CodeWhat Asterarium actually draws from real data, and how one constraint — not a single line of code runs on a server — shapes everything from the layer boundaries to the order of work in each frame.
Astronomy: Where the Stars AreTurning a place and a time into a direction in the sky, along two deliberately different paths: stars are fixed at build time, solar-system bodies are computed every frame.
Coordinate Frames and the Orientation of the SkyWhy three coordinate frames coexist, why the observer sits at the world origin, and where the single matrix that turns the celestial group comes from.
The Data PipelineStars ship as a fixed-layout binary, constellation lines and cities as JSON — all settled at build time, so the browser only loads and draws.
Rendering the Atmosphere and the StarsThe midday sky that came out pitch black when a physical atmosphere model met the browser, and the law that turns a point source into a star the eye believes.
Depth Rules and the Bugs Behind ThemThe sky is painted as a post-processing pass keyed on depth, so every depth decision shows up on screen. The bugs that appeared, and the rules they left behind.
State and the Frame LoopValues that change sixty times a second and settings that change when someone clicks belong in different places. Here is where the line falls, and the rules that grew out of it.
Delivery and the Standalone PagesHow a site with no server-side code is shipped, where the multi-megabyte assets come from, and how eight standalone 3D pages are kept from carrying each other's code in a form a machine can check.
VerificationAstronomical values you cannot work out by hand are pinned to known figures, inverted conventions (azimuth measured from south, say) are caught with assertions about direction, property-based tests cover the whole domain, and finally the drawn pixels themselves are checked in a real browser.
Design Principles, in SummaryThe five principles that run through decisions as different as astronomy and asset delivery, and how each of them connects back to one constraint: no server-side code.

Read from the first section →Glossary → Every annotated term in one list, grouped into astronomy, graphics, web and Asterarium-specific words.