Newtonian N-Body Solar System Simulator (Phase 3)

A high-performance Newtonian gravity simulation of the solar system featuring 3,650+ objects (Sun, planets, Pluto, 20 major moons, 2,000+ real asteroids, famous comets, Kuiper Belt dwarf planets, and Oort Cloud detached objects), set against a backdrop of 1,600+ real fixed background stars from the Yale Bright Star Catalog.

Phase 3 Features

• Surface Point-of-View (PoV) Viewports: Witness the sky and horizon directly from the surface of solar system bodies! Includes six predefined POIs:
  • Munich, Germany (Earth): Watch the diurnal star rotation and Sun transitions.
  • Apollo 17 Landing Spot (Moon): Stand in the Taurus-Littrow valley and witness a tidally locked Earth rise.
  • Mare Orientale Limb (Moon): Stand on the edge of the Moon's Orientale basin and observe Earth libration rising and setting.
  • Gale Crater (Mars): Stand in Gale Crater and track Phobos/Deimos transiting the Sun.
  • Venera 13 Spot (Venus): Experience the slow daylight transits under a thick yellowish sky.
  • Huygens Landing (Titan): Observe Saturn rising/setting along the horizon in an orange hazy sky.
• True Rotational Geometries: Simulates rotation speeds, obliquities, pole tilts (RA/Dec coordinates of the north pole), and Prime Meridian angles (W_0) for major planetary bodies based on real IAU pole models.
• Horizon & Atmosphere Rendering: Draws day/night vertical color gradient skies based on local Sun altitudes, featuring glowing scattering halos around the Sun and custom mountain silhouette horizons matching the body type. Silhouettes rotate dynamically relative to the line-of-sight Azimuth.
• CPU-Based UV Spherical Planet Texturing: Decodes equirectangular 1K planetary maps using Sean Barrett's header-only stb_image.h and maps them onto spheres using a custom software UV mapper with Lambertian lighting shading (visualizing planetary phases).

Quick Start

1. Requirements

Install SDL3 and nlohmann-json using Homebrew (macOS):

brew install sdl3 nlohmann-json

Ensure Python and uv are available.

2. Fetch Extended Orbital & Star States

Run the data exporter to query JPL Horizons (massive planets), the JPL Small-Body Database (2,200 asteroids and comets), and VizieR (fixed stars) for our simulation epoch (2026年06月28日):

# This will write extended_state.json and download 1K planetary textures to textures/
uv run python fetch_extended_state.py --asteroids-limit 2200

3. Build the Simulator (C++)

Use CMake and Ninja to compile:

cmake -B build -G Ninja
cmake --build build --config Release

4. Run

./build/solar

Interactive Controls

Viewport Camera Controls

• Left Mouse Drag:
  • Space Overview Camera: Rotate camera yaw and pitch around the focused body.
  • Surface Viewport Camera: Pan the observer's looking direction (changes Azimuth and Altitude).
• Right Mouse Drag:
  • Space Overview Camera: Pan the camera viewport parallel to the screen.
  • Surface Viewport Camera: Pan offsets.
• Scroll Wheel: Zoom in / out (acts as a camera focal length zoom in surface mode).
• [Tab]: Cycle camera focus targets in space mode (Overview -> Sun -> Planets -> Moons -> Comets).
• [Arrow Keys]: Look around (rotate camera Yaw/Pitch, or Azimuth/Altitude in surface viewpoint mode). Hold [Shift] for fine-precision adjustments.
• [R]: Reset camera offsets and rotation to default top-down overview.

Simulation Controls

• [P]: Cycle viewpoints (Space Overview -> Munich, Germany -> Apollo 17 -> Mare Orientale Limb -> Gale Crater -> Venera 13 -> Huygens Landing -> Space Overview).
• [Space]: Pause / Resume physics propagation.
• [ and ]: Decrease / Increase simulation time warp speed (magnitude).
• [I]: Invert time direction (flips simulation speed to positive or negative to run backwards).
• [N]: Reset simulation to the current real-world time ("now") and catch up coordinates.
• [S]: Toggle background stars ON / OFF.
• [A]: Toggle asteroids and comets display ON / OFF.
• [T]: Toggle orbital trails.
• [L]: Toggle body sizing (Logarithmic Visibility vs. Physical Scale).
• [H]: Toggle HUD layout ON / OFF.

Codebase Architecture

• fetch_extended_state.py: Python data query script. Solves Kepler's equations to compute Cartesian coordinates from Keplerian elements for asteroids/comets, downloads Yale Bright Stars coordinates, caches API responses, and downloads 1K planet textures.
• src/physics.hpp: Declares the Body and Star structures, and adds J2000 pole element properties (alpha0, delta0, W0, rotation_period).
• src/physics.cpp: Implements J2000 epoch JD parser, N-body / restricted N-body Verlet solvers, and rotational dynamics pole coordinates.
• src/renderer.hpp: Declares the renderer parameters, custom Texture structures, PointOfInterest models, and horizon projection functions.
• src/renderer.cpp: Implements perspective surface projection methods, coordinate basis rotations, CPU UV software texture mapping, day/night atmospheric gradients, horizon hills, and Sinclair font overlay.
• src/main.cpp: Program entry loop driving the sub-stepping physics engine and coordinating frames.

Credits and Acknowledgements

• Planetary Textures: Equirectangular projection maps for the Sun, planets, and Earth's Moon are sourced from Jerome Etienne's open-source threex.planets project. Equirectangular textures for major moons (Io, Europa, Ganymede, Callisto, Titan, Triton, Charon, Enceladus, Miranda, Oberon, Titania), the Earth's cloud overlay, and Ceres are sourced from the open-source CSS-Sol-Star-System repository. All images are originally compiled or derived from NASA, ESA, Solar System Scope, and USGS planetary maps.
• Image Loading Library (stb_image.h): Single-header image parsing library written by Sean Barrett (nothings) and community contributors. Released under the Public Domain (MIT License option).