Astrarium

Interactive 3D visualisations of the solar system, the Milky Way, and the observable universe. Built with Three.js, bundled by Vite, served as static HTML.

Named after the Astrarium of Giovanni de’ Dondi (completed 1364) — a medieval clockwork model of the solar system that displayed the motions of the Sun, Moon, and the five planets known at the time. This project is a spiritual descendant: same idea, modern tools, seven centuries later.

About this project

Astrarium is 100% vibe-coded — every change is driven by an AI pair-programmer working from a filed GitLab issue. The project’s secondary purpose is to stress-test a tight Git workflow (issue → assign → draft MR → squash → tag → deploy) under that mode of work. Outside contributors are welcome — see CONTRIBUTING.md for the workflow, and join the live conversation on the Astrarium Discord.

Live

https://astrarium42.gitlab.io/astrarium/ — deploys on vX.Y.Z tag pushes via .gitlab-ci.yml. No further configuration.

Contributing

See CONTRIBUTING.md for the git workflow, commit style, and the docs-match-code rule. Short read — a couple of minutes.

The four views

View	What it shows	What’s accurate	What’s compressed
`solar-system.html`	All 8 planets + moons in a visually pleasing scale	Orbital periods (Mercury really is 4× faster than Earth)	Sizes & distances
`scale.html`	True sizes and distances	Everything. You can measure light-time to Jupiter.	Nothing — and that’s the point
`galaxy.html`	The Milky Way with the Sun in it	Differential rotation via flat rotation curve (ω = v_c / r)	Galaxy size vs. star sizes
`universe.html`	Hierarchical zoom from Local Group to observable universe	Real RA/Dec positions for named objects (Andromeda, Virgo Cluster, Great Attractor…)	Scales across 10⁴ orders of magnitude

See docs/scales.md for exactly which cheats happen where, and docs/physics.md for the formulas.

Data

All real astronomical values live in src/data/:

constants.js — speed of light, AU, light-year, etc.
planets.js — radii, orbits, periods, axial tilts for all 8 planets
moons.js — 15 major moons with real orbits

Physics formulas are in src/physics/formulas.js — Kepler, Lorentz, unit conversions.

Running locally

Node 20+ is required. One-time install, then start the dev server:

npm install
npm run dev          # Vite dev server with hot-module reload

Other scripts:

npm run build        # production build into dist/
npm run preview      # serve the built dist/ for verification
npm run lint         # ESLint
npm run format       # Prettier (rewrites in place)
npm run format:check # Prettier (verify only, no rewrite)

Running tests

Pure-JS unit tests for src/physics/ and src/data/ run via Node’s built-in test runner. No bundler involved.

npm test

Project structure

See docs/architecture.md.

├── index.html              Landing page
├── solar-system.html       Compressed view of the solar system
├── scale.html              True-scale view of the solar system
├── galaxy.html             Milky Way
├── universe.html           Cosmic hierarchy
├── src/
│   ├── data/               Astronomical constants & tables
│   └── physics/            Reusable formulas
└── docs/                   Physics notes, scale rationale, architecture

Controls (common to all views)

Mouse drag — rotate
Scroll — zoom
Right-drag — pan
Time-speed slider — scales the orbital animation speed
Pause / Reset — obvious
Labels / Orbits / Trails checkboxes — toggle overlays

Language

The UI labels are in French. The code, comments, and documentation are in English. Contributions welcome in either.

Credits

Planet, Sun, and Moon textures — Solar System Scope (CC-BY 4.0). The 4K-class maps for the Sun, all 8 planets, Earth’s Moon, and Saturn’s ring live in src/textures/images/. The original procedural Canvas2D textures remain in src/textures/procedural.js as a runtime fallback.
Phobos / Deimos / Miranda / Oberon textures — public-domain cylindrical mosaics via solarviews.com: Phobos (USGS), Deimos (Philip Stooke, with Chris Jongkind and Megan Arntz), Miranda and Oberon (USGS, from Voyager 2 imagery).
Titania texture — public-domain cylindrical mosaic from Voyager 2 data by USGS / Tammy Becker and JPL / Caltech, via NASA Science 3D Resources.
Bright-star catalog — ESA Hipparcos main catalogue (public domain), trimmed to magnitude ≤ 6.5 via the gmiller123456/hip2000 JSON conversion.
Star proper names — IAU Catalog of Star Names (IAU-CSN) by the IAU Working Group on Star Names (CC-BY).
Constellation stick figures — line data adapted from Stellarium’s western_SnT sky culture (Sky & Telescope, GPL-2.0+), used as the source for src/data/constellations.js.
Astronomical data — NASA (public domain).
Rendering — Three.js, bundled with Vite (tree-shaken, no CDN dependency).

License

MIT for the code. Astronomical data is in the public domain. Planet textures are © Solar System Scope under CC-BY 4.0; redistributions must preserve that attribution.

← Astrarium