Astrial API & Spacecraft API

Keplerian Orbital Elements

All orbital calculations are based on six orbital elements that uniquely define an object's elliptical orbit:

Element	Symbol	Meaning
Semi-major axis	a	Mean distance from Sun (in AU)
Eccentricity	e	Orbit shape (0 = circle, 0-1 = ellipse)
Inclination	i	Angle to ecliptic plane
Longitude of ascending node	N	Orientation of orbit in 3D space
Argument of perihelion	w	Angle to perihelion (closest point)
Mean anomaly	M	Current position in orbit (0-360°)

Position Calculation Flow

SolarApp calculates celestial body positions through a deterministic pipeline:

1. Time to Days Conversion: Utils.AstralTime(DateTime) converts any date/time to days since December 31, 1999 (J2000 epoch reference).
2. Orbital Element Updates: Each celestial body updates its orbital elements based on elapsed time. Planets use polynomial coefficients; asteroids use fixed elements.
3. Kepler's Equation Solver: The Newton-Raphson numerical method solves Kepler's equation to compute eccentric anomaly from mean anomaly.
4. 3D Position Calculation: Convert from orbital coordinates to 3D heliocentric Cartesian coordinates (X, Y, Z).
5. Hierarchical Positioning: Moons calculate position relative to their parent planet, then offset by the parent's heliocentric position.

The Astrial API

AstrialAPI is the core physics library providing:

Celestial Body Models

• Sun — Reference frame origin; no orbital calculation needed
• Planet — Eight planets with time-varying orbital elements and rotation models
• Moon — Satellites with hierarchical orbit calculations relative to parent
• MinorBody — Asteroids, dwarf planets, comets with fixed or precessing orbits

Each implements DeterminePosition(double time) to compute heliocentric or planet-centric coordinates.

Kepler Solver

The Newton-Raphson solver in the shared DeterminePosition() method solves:

M = E - e * sin(E)

where:
  M = Mean anomaly (input, derived from time)
  E = Eccentric anomaly (output)
  e = Eccentricity

The iterative formula is:

E_{n+1} = E_n - (E_n - e * sin(E_n) - M) / (1 - e * cos(E_n))

This converges rapidly (typically 2-3 iterations) for elliptical orbits with e < 1.

3D Coordinate Transformation

Once eccentric anomaly E is found, compute:

// True anomaly
ν = 2 * atan2(sqrt(1+e) * sin(E/2), sqrt(1-e) * cos(E/2))

// Distance from focus (Sun)
r = a * (1 - e * cos(E))

// Orbital plane coordinates
x_orb = r * cos(ν)
y_orb = r * sin(ν)

// Rotate to heliocentric ecliptic frame using orbital elements (N, i, w)

The Spacecraft API

SpaceCraftAPI extends orbital mechanics for trajectory planning and maneuver design:

Maneuver Planning

• Hohmann & Escape Transfers — Orbit-to-orbit transfers, cislunar injections, and planet-escape trajectories aimed at heliocentric targets
• Gravity Assists & Free Returns — Closed-loop slingshot solving with post-flyby heading targets, plus Apollo-style free-return trajectories
• Lambert's Problem — Pure-Kepler transfer grids that pick launch windows and seed the injection burns for numerical refinement
• Launch & Capture — Closed-loop surface-to-orbit ascents and arrival insertions solved against the integrated trajectory

These phase solvers are composed by the mission compiler, which turns declarative mission JSON into a fully solved multi-leg course — see the Missions deep dive.

Trajectory Propagation

Spacecraft state (position, velocity, mass) is propagated with an adaptive-substep N-body integrator accounting for:

• Solar gravity (dominant)
• Planetary and lunar gravity (moving sources, updated every substep)
• Finite burns (thrust and mass flow from the craft's engine and tank sections)

Substep size adapts to both the craft's speed/acceleration ratio and each gravity source's free-fall timescale, so fast planetary encounters integrate finely even when heliocentric velocity is huge.

Porkchop Analysis

A "porkchop plot" computes the Δv requirement for all combinations of departure and arrival times across a mission window. In the current pipeline these pure-Kepler grids serve as the seed for the closed-loop solvers, which refine the winning cell against the full N-body integration.

Gravitational Influence & Hierarchies

SolarApp uses a heliocentric model as the primary frame, with planet-centric sub-frames for moons:

This avoids accumulating numerical errors that would occur if every moon orbited the Sun directly. Secondary perturbations (e.g., Jupiter's gravity on Saturn's moons) are negligible at rendering scale.

Data Sources & Accuracy

SolarApp loads orbital elements from authoritative sources:

• MPC (Minor Planet Center) — Asteroid and comet orbital elements, updated regularly
• JPL Horizons — High-precision planetary and satellite ephemerides
• DE430/DE440 Ephemeris — NASA's Development Ephemeris for long-term accuracy

Accuracy is typically ±1% in position for modern data, sufficient for visualisation. For deep-space navigation, higher-order perturbations and relativistic corrections would be needed.

Real-Time Performance

SolarApp maintains 60 FPS by:

• Vectorized math — Using Vector3 operations and SIMD where possible
• Lazy evaluation — Calculating only visible bodies each frame
• Spatial queries — Culling orbits and bodies outside camera view
• Caching — Pre-computing common trigonometric values

Integration with the 3D API

The Astrial 3D API bridges orbital mechanics and rendering:

• Query 3D positions for any celestial body at any time
• Get orbital velocity vectors for trajectory visualization
• Retrieve orbital elements for UI display and mission planning
• Predict future positions for trajectory trails and projections

This clean separation allows the rendering layer to focus on visualization while the Astrial API handles all celestial mechanics.

Going Deeper

For the complete mathematical derivation, see the project README which includes Newton-Raphson convergence analysis and numerical stability discussions.