solargod/README.md

SOLARGOD ▸ Orrery

A standalone, browser-based 3D solar-system explorer — the interplanetary sibling of GODSIGH, which watches Earth. Float above a compressed-scale ("MEGA") solar system with every world visible at once, moving on real JPL ephemerides; scrub a time bar across six thousand years; fly the camera into orbit around any planet, its moons circling, textured and tidally locked; toggle TRUE scale and watch the system animate out into its real, humbling emptiness. Live layers plot where Voyager 1, JWST and Parker Solar Probe are right now, real main-belt asteroids, comets, and near-Earth close-approaches on their true orbits — and a computed almanac of oppositions and elongations on the time bar. Everything is client-side, free, keyless, and runs fully offline.

Quickstart

python3 serve.py          # stdlib only — no npm, no build step
# open http://127.0.0.1:8147

serve.py statically serves the app and proxies the JPL feeds a browser can't call directly (Horizons / SBDB / CAD — no CORS), with a disk cache in cache/. Three.js is vendored under vendor/three/, so the app runs with no CDN. The deterministic core (Sun, planets, moons, orbits, sky events, time travel) runs with zero network calls — positions are computed locally from Keplerian elements; network layers (spacecraft, asteroids, comets, close-approaches) are additive and fail soft.

Verify

Open http://127.0.0.1:8147/verify.html — an in-browser gate runner that checks the ephemeris against JPL Horizons ground truth (hard-coded checkpoints + live queries through the proxy). All 22 gates should read PASS, e.g.:

Gate	Result
Mars / Jupiter / Earth @ 2026-07-15 (heliocentric ecliptic AU)	Δ ≤ 3.3e-4 / 2.9e-3 / 3.9e-5 AU
Kepler @ e=0.97 · orbitPath closes · frame round-trips · MEGA→TRUE keeps direction	exact
Mars @ J2000 · Jupiter @ 1900 vs live Horizons	Δ 4.8e-5 / 2.0e-3 AU
Main belt between Mars & Jupiter · Halley aphelion beyond Neptune	pass
Voyager 1 @ 2026-07-15 = (−32.07, −136.21, +98.55) AU · JWST hugs Earth	Δ 0.002 / 0.011 AU
NEO propagated miss vs CAD (real orbit)	≤ 25% (median ~0.6%)
Sky events — Mars opposition ±2 d of 2027-02-19 · Venus elongation cadence · nextEvent	pass
Deep time — Jupiter @ 1000 BC · Mercury @ 2500 vs live Horizons (Table 2a/2b)	Δ 0.004 / 3.3e-5 AU
Event band maps the ±2 yr window to full width	pass

Layers

Layer	Source	Default	Notes
Planets & orbits	JPL SSD approximate elements (Standish)	on	8 planets + Pluto, textured, MEGA-compressed orbit paths
Body labels	—	on	names; the focused body's children also get distance labels
Moons	NASA/USGS mosaics	on	21 moons, per-parent compression, retrograde Triton; 8 with real surfaces, tidally locked; grayscale mosaics directorially tinted (Titan orange, Europa tan…)
Rings	true km, scaled to parent	on	Saturn (textured annulus) · Uranus (schematic)
Spacecraft	JPL Horizons (proxy)	on	Voyager 1/2, New Horizons, JWST, Parker, Juno, Lucy, Psyche — live distance + one-way light-time
Main belt	JPL SBDB (proxy)	off	~1500 main-belt asteroids, shared Kepler core
Comets	JPL SBDB (proxy)	on	1P/Halley, 2P/Encke, 67P, 96P — full orbits + anti-sunward 1/r² tail
Close approaches	JPL CAD + SBDB (proxy)	off	±30-day NEOs at their true propagated positions with real orbits (per-object fail-soft to a schematic ring); miss distance in lunar distances
Sky events	computed (no network)	on	oppositions, conjunctions & greatest elongations as diamonds on the timeline's event band; click one to jump the clock

Controls

• Focus — click any body (or use the Focus menu) → the camera flies into orbit around it; breadcrumb SOL ▸ JUPITER ▸ EUROPA; Esc steps out one level.
• MEGA / TRUE — toggle the scale mode; the transition animates over ~2.5 s.
• Epoch — 1800–2050 / 3000 BC – 3000 AD: switch to the extended Table 2a/2b range (reloads the session, carried in the hash as &e=1).
• Body scale — 1× / 100× / 1200× radius exaggeration.
• Time bar — NOW, play/pause, reverse, rate presets (1× · 1 min/s … 1 yr/s, plus 1 decade/s · 1 century/s for deep time), a scrubbable timeline, and an event band below it mapping the computed ±2 yr window to full width (a bracket on the main strip marks its extent). A LIVE / SCRUBBED chip mirrors GODSIGH.
• Info panel — appears on focus: a grimoire card with a physical fact sheet, hand-written prose, a stylized portrait, and live computed facts (distance from Sun & Earth, sunlight age, orbital speed, day & year length, and the next opposition/elongation). Focusing Earth reveals a link to the GODSIGH world view.
• Shareable URLs — the view serializes to the hash (#f=<body>&t=<time>&s=<mega|true>&L=<layers>&cam=…&e=<0|1>); paste one to reproduce a view.
• ?debug=1 — frame-rate / scale readout.

Architecture

No build step, no framework, plain ES modules; Three.js vendored offline. One module owns the truth→view transform (scale.js); every position is computed in real heliocentric J2000 ecliptic AU first (ephem.js) then compressed. A floating origin subtracts the focused body's position in float64 before writing to the scene graph, so a focused planet never jitters at close zoom.

index.html · serve.py · verify.html
css/style.css · vendor/three/ (vendored, MIT)
js/  config lib ephem bodies scale ui main
js/layers/  planets moons rings spacecraft asteroids comets neos events almanac
assets/textures/ (CC BY + NASA/USGS public domain)  ·  assets/art/grimoire/ (generated)

The full execution spec is SOLARGOD_BRIEF.md; wave-2 polish is PERIHELION_BRIEF.md.

Credits

• Positions — JPL SSD approximate elements; live feeds via JPL Horizons / SBDB / CAD.
• Planet/Sun/ring/sky textures — Solar System Scope, CC BY 4.0.
• Moon surfaces — NASA/USGS Astrogeology mosaics (public domain); grayscale ones directorially colour-tinted. See assets/textures/CREDITS.md.
• Grimoire art — generated locally with MODELBEAST / FLUX (see assets/art/PROMPTS.md); the aesthetic layer only — real worlds get real data.
• Built on Three.js (r170, vendored, MIT).