Solar-Wanderer

---

🌌 Why this matters

We all learned the names of the planets as children. But have you ever been there?

Most space apps make you choose: either scientifically accurate, or beautiful and immersive. Solar Wanderer does both. It puts the real solar system — every planet, every moon, every AU — into a web page that anyone can open, on any device, for free.

Our mission is simple:

Before humanity becomes an interstellar species, we must first truly see our own backyard.

When a child stands on the Moon, turns around, and sees Earth as a tiny blue marble in the black sky, something changes. When a student pulls back from Earth until the planets shrink to dots and the Oort Cloud appears, their sense of scale changes forever. When a teacher can take an entire classroom to Mars in five minutes, science education changes.

This is not just a simulation. It is an invitation.

---

✨ What makes it different

	Solar Wanderer
Scale	True 1:1 km — every planet, every moon, every AU, from 0.5 m to 100,000 AU
Accuracy	NASA JPL Horizons verified · ≤0.074° for planets · 21 moons fitted from state vectors
Immersion	Seamless descent from orbit → atmosphere → surface → walking → underwater (no cuts, no loading)
Scope	Sun to the Oort Cloud (100,000 AU) · asteroid belt · Kuiper belt · 28 real TNOs · 4 comets · past the heliopause where Voyager 1 & 2 are now
Anywhere	Desktop keyboard/mouse and full mobile touch — same physics, same scale
Size	~200 kB gzipped JS · no server · no GPU farm
Open	MIT licensed · all data from public NASA/IAU sources · verifiable against JPL Horizons

---

🎯 The Road Ahead: Help us build the first interstellar stepping stone

Solar Wanderer already works. But to become indistinguishable from reality and reach billions of people, we need your help.

We are building toward four pillars:

1. 🪐 Realism that is indistinguishable from reality

   • Real global DEM terrain: Moon (LOLA), Mars (MOLA), Earth (ETOPO1); local HiRISE / photographic surface detail remains future work
   • Real solar/lunar/planetary eclipse shadows
   • Dynamic weather, clouds, dust storms, auroras
   • High-resolution 16K–32K textures
   • Real spacecraft with 3D models and mission histories

2. 🥽 Immersion that makes you feel you are there

   • WebXR / VR support
   • First-person spacesuit HUD
   • Environmental storytelling: Apollo landing sites, rover tracks, landmarks
   • Dynamic time-of-day and seasonal visuals
   • Spatial orientation aids and scale references

3. 📚 A public science education system

   • Structured guided tours and courses
   • Voice narration in multiple languages
   • Teacher/classroom/museum toolkits
   • Real-time astronomical event simulations
   • A scalable content platform for facts, stories, and lessons

4. 🌍 Reach: let the world know

   • Multi-language support
   • Video content, blogs, SEO
   • Partnerships with schools, museums, planetariums, and space agencies
   • Community-driven content and translations

👉 See the full master plan: ROADMAP.md

---

🙌 How to contribute

We welcome contributors of all kinds: developers, astronomers, educators, translators, designers, writers, video creators, and space enthusiasts.

Quick start

git clone https://github.com/hyqzz/Solar-Wanderer.git
cd Solar-Wanderer
npm install
npm run dev      # → http://localhost:5173
npm test         # 33 precision tests (no network needed)
npm run verify   # live cross-check against NASA JPL Horizons (needs internet)

Most wanted contributions

Area	What’s needed	Good first issue?
Real terrain	USGS LOLA (Moon) / MOLA (Mars) DEM tile streaming	⭐ Yes
Eclipse shadows	Sun–Moon–Earth shadow volumes	Advanced
Sound	Ambient radio hiss, surface crunch, underwater	⭐ Yes
Translations	English/Chinese already done; Japanese, Spanish, French, Arabic…	⭐ Yes
Education content	Guided tours, facts, quizzes, lesson plans	⭐ Yes
VR / WebXR	Immersive headset support	Advanced
Accuracy	VSOP87 + ELP2000 for ±3000 year validity	Advanced
Bookmarks	Save/restore position + time	⭐ Yes
Spacecraft models	Voyager, New Horizons, Juno, Cassini 3D models and trajectories	⭐ Yes
Outreach	Blog posts, videos, social media, school partnerships	⭐ Yes

Check our Issues tab — we are turning the master plan into actionable issues. Pick one, comment, and jump in.

Please read CONTRIBUTING.md for code style and PR process.

---

🎮 Try it now

https://sw.icodestar.net

No install. No account. Just open and go.

Recommended first experiences:

1. Open the directory → tap Moon → pinch all the way in → land → look up: the blue Earth hangs in the black sky.
2. Pull back from Earth until the planets become dots, then keep going until the Oort Cloud appears.
3. Double-click Saturn and zoom in until you can see the Cassini Division in the rings.

---

🛠 Tech stack

• Three.js 0.165 · Vite 5 · native ESM · WebGL2 · logarithmic depth buffer
• Pure-function ephemeris layer (Node-testable)
• Floating-origin rendering for 1:1 km scale
• GPU auto-tiering across three tiers (High / Medium / Low), by GPU generation rather than vendor alone

Quality tiers

The app picks a tier from the WebGL renderer string, then keeps adjusting the render scale at runtime to hold the frame rate. Physical scale, DEM and ephemerides are identical in all three tiers — only rendering work differs.

Tier	Picked for	What it adds
High	RTX / GTX 1060+ / RX 5500+ / Arc A / Apple M-Pro·Max·Ultra	Volumetric clouds, 1.5× pixel ratio, 8K textures, 2048 shadow maps
Medium	Mid-range and older discrete GPUs (GTX 750 Ti–980, RX 480–550, base Apple M1/M2/M3)	Procedural surface detail, 4K textures, 1536 shadow maps — no volumetric clouds
Low	Integrated GPUs, software rendering, mobile	Flat shading detail off, 1024 shadow maps

Override with ?quality=high, ?quality=medium or ?quality=low (lite is accepted as an alias for low). Volumetric clouds are High-only: measured on the same scene they cost about 3.2× Medium, and Medium is already 2.0× Low.

---

📊 Accuracy

Model	Validation and coverage
Sampled JPL states (65 targets)	2025-01-01 through 2035-01-01 TDB, sharded by year; off-grid comparisons across the whole window pass <0.001° and <10 km
Planet fallback	VSOP87 / analytic models; use npm run verify for live comparison
Moon fallback	Complete Meeus periodic terms; checked separately when sampled states are unavailable
Satellite fallback	Empirical fitted elements from a 7-epoch least-squares fit; ~0.003° at the fit epoch, degrading to ~2° within 180 days (tracked by tests, not hidden)
Rotation	IAU models; independent of the sampled orbital states

Sample interpolation differences are not absolute physical uncertainties. States load progressively, one year-shard at a time, so a 10-year window costs roughly the same per body as the previous 16-month window; outside the shard that is loaded, or during resource failures, the application uses approximate models, identified per target in the HUD. Refresh with npm run fetch-ephemeris (resumable; cached shards are reused) and validate with npm run verify-release before extending the interval.

The renderer does not yet reproduce every surface at photographic detail. Global DEM tiles are coarse, unobserved regions use procedural assumptions, and clouds / solar and comet activity are not current observation reconstructions. Release evidence and limitations distinguish integrated-GPU Low, discrete-GPU High, and hardware that has not been tested.

---

📣 Spread the word

If Solar Wanderer made you feel small in a good way, please:

• ⭐ Star this repo
• 🔗 Share sw.icodestar.net
• 📺 Make a video or write a post about your experience
• 🏫 Tell a teacher, a student, or a museum curator

Together, we can make the solar system feel like home — and prepare humanity for the stars.

---

Credits

Ephemerides	NASA JPL (Standish 1992 planetary elements · Horizons API state vectors)
Textures	Solar System Scope CC-BY-4.0 · Steve Albers SOS · NASA JPL Photojournal (public domain)
Rotation models	IAU/WGCCRE reports
Bright stars	Hipparcos catalog

---