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 Transfers — Efficient orbit-to-orbit transfers using two impulses
• Gravity Assists — Slingshot maneuvers to change velocity without fuel
• Lambert's Problem — Find impulsive trajectories between two points in time

Trajectory Propagation

Spacecraft state (position, velocity, mass) is propagated using high-order numerical integration (RK4 or RK45) accounting for:

• Solar gravity (dominant)
• Planetary perturbations (secondary)
• Impulsive burns (Δv applications)

Porkchop Analysis

A "porkchop plot" computes the Δv requirement for all combinations of departure and arrival times across a mission window. This is computationally intensive but enables discovery of optimal launch windows.

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.