3D Simulation Technical Guide

This guide explains how the Interactive 3D Solar System Simulation works under the hood. It covers the mathematical foundations, the calculation order, and how each orbital parameter is configured.

Developer Quick Start

The simulation lives in a single file: script.js (~30,000 lines). Here are the five functions you’ll touch most:

Where to look first: Object definitions (lines ~1835–3708) define every celestial body’s parameters. The hierarchy wiring (lines ~4525–4624) shows which object is nested inside which. These two sections plus moveModel cover 80% of what the simulation does.

Core Principles

The simulation is built in Three.js  and uses two fundamental units:

Since the circumference of a circle is 2πr, all orbital calculations derive from these base values:

• Time: All periods are expressed relative to one solar year = 2π
• Distance: All distances are expressed relative to 1 AU = 100

The Geocentric Frame

The simulation places Earth at the center of the scene — a geocentric reference frame. The Sun orbits Earth (not the other way around), and all planets revolve around the Sun, which itself revolves around Earth. This is a natural choice because the model describes precession cycles as seen from Earth’s reference frame.

How it works in the 3D scene:

The Sun has speed: 2π — exactly one revolution per year around barycenterEarthAndSun. Since barycenterEarthAndSun is nested inside Earth’s precession hierarchy, the Sun inherits all of Earth’s precession rotations while orbiting at 1 AU.

For other planets, a yearly revolution sandwich converts heliocentric orbits into the geocentric frame:

PerihelionFromEarth         (speed: +2π/yr, perihelion offset position)
  └── ...
      └── RealPerihelionAtSun  (speed: −2π/yr, orbit size, inclination tilt)
            └── Planet          (own orbital speed)

The +2π layer makes the planet’s orbit center revolve at the same rate as the Sun — keeping the planet centered on the Sun as seen from Earth. The −2π layer cancels this revolution for the orbit inside, so the planet orbits at its own heliocentric rate. The net effect: the planet orbits the Sun, which orbits Earth, producing the correct apparent geocentric motion (annual retrograde loops, elongations, and zodiac transit).

Start Date Alignment

The simulation’s start date is aligned to the June Solstice of 21 June 2000, 00:00 UTC.

At this moment, the Sun was at its highest declination (RA ~6h / ~18h), corresponding to maximum obliquity effect.

Source Code & Data

• Simulation code: Available on GitHub  (see the simulation source files)
• Interactive mind map: Explore the simulation’s structure at mindmap.holisticuniverse.com 
• Excel spreadsheet: The full spreadsheet with all settings and calculations is available on request
• Configuration: All values in the simulation match the Formulas and the theory described in this documentation

Code Architecture

The simulation lives in a single file (script.js, ~30,000 lines) built on Three.js  with dat.gui  for controls. The code is organized into five major blocks:

1. Constants & Derived Values (top ~1,800 lines)

All model parameters are declared upfront as constants — nothing is hard-coded deeper in the file. From these inputs, the code derives all secondary values: precession cycle lengths (H/3, H/5, H/8, H/13, H/16), the Balanced Year, gravitational parameters, planetary masses, and AU distances.

An OrbitalFormulas object provides reusable helper functions: Kepler’s equation solver, mean/true anomaly conversion, orbital velocity, semi-axis calculations, and heliocentric distance.

2. Scene Construction (~lines 1,800–6,000)

Each celestial body is defined as a JavaScript object with orbital parameters (speed, tilt, eccentricity, start position, precession period). Three.js builds a nested hierarchy of 3D containers:

scene
└── startingPoint
    ├── earthWobbleCenter (fixed at origin, visualization only)
    ├── earth (axial precession, −H/13)
    │   ├── earthInclinationPrecession (+H/3)
    │   │   ├── midEccentricityOrbit (visualization helper, sibling)
    │   │   └── earthEclipticPrecession (+H/5, tilt −0.634°)
    │   │       └── earthObliquityPrecession (−H/8, tilt +0.634°)
    │   │           └── earthPerihelionPrecession1 (+H/16)
    │   │               └── earthPerihelionPrecession2 (−H/16, eccentricity offset)
    │   │                   └── barycenterEarthAndSun
    │   │                       ├── sun (1 AU, speed 2π/yr)
    │   │                       ├── earthPerihelionFromEarth (copy of barycenter position)
    │   │                       ├── moon (6 precession layers under earth.pivotObj)
    │   │                       └── mercury … neptune (5-layer hierarchy each)
    │   └── rotationAxis (axial tilt, celestial sphere)
    └── invariable plane, stars, constellations, Milky Way

Each precession cycle is a separate container rotating at its own rate. Because the containers are nested, each rotation is applied on top of the previous one — the physical principle of superimposed precessions maps directly to Three.js parent-child transforms.

Earth is unique in this hierarchy: it has six nested precession layers (the two counter-rotating reference points from the model). earthWobbleCenter is a separate visualization object fixed at the origin — it is not a parent container of earth. All other planets use a 5-layer hierarchy (perihelion precession sandwich + yearly geocentric revolution + orbit frame + planet), with inclination oscillation computed analytically rather than geometrically.

3. GUI & Controls (~lines 6,000–12,800)

The dat.gui panel provides:

• Date/time input — type any date or Julian Day; the simulation jumps to that epoch
• Simulation controls — run/pause, speed selection (1 second = 1 real second up to 1,000 years), step forward/backward, tracing
• Planet hierarchy inspector — live display of every object’s position, rotation, and orbital elements, exportable to Excel
• Predictions panel — live readout of day/year lengths, precession periods, obliquity, eccentricity, inclination, and perihelion longitude at the current epoch

4. Animation Loop (~line 12,838)

The render() function runs every frame and advances the universal time counter:

o.pos += speedFactor × speed × delta

To balance accuracy with performance, updates are split into tiers:

• Every frame: orbital positions (moveModel), orbit traces, camera
• 20 Hz: date/time display
• 10 Hz: heavy astronomy (inclinations, invariable plane balance, predictions, anomalies)
• 30 Hz: visual effects (lighting, lens flare, glow)

5. Position Calculations (~lines 25,000+)

moveModel(pos) is the core function. For each object it computes:

θ = obj.speed × pos − obj.startPos × (π / 180)

Then it positions the object by rotating its orbitObj:

orbitObj.rotation.y = θ

All orbits in the simulation are circular — every object has a === b (semi-major equals semi-minor axis). This is a core design principle: the model builds complex orbital motion entirely from uniform circular rotations layered through the nested container hierarchy, not from ellipse equations. The elliptical paths observed in nature emerge from the superposition of multiple circular motions at different rates.

Then updatePositions() transforms world-space coordinates into Earth’s equatorial frame to compute RA/Dec for every planet — entirely in the browser, no external APIs.

Input Parameter Reference

The simulation is driven by a set of input constants. All other values (day lengths, year lengths, precession rates, orbital positions) are derived from these inputs. For the complete list of values, see Configuration: Simulation Input Constants.

Core Cycle Parameters

Year & Day Length Parameters

Model Start Position Parameters

Obliquity Parameters

Eccentricity Parameters

Longitude of Perihelion Parameters

Physical Constants

Calculation Order

The precession movements must be applied in a specific order. In Three.js, each movement is nested inside the previous one:

earth.pivotObj.add(earthInclinationPrecession.containerObj);
earthInclinationPrecession.pivotObj.add(earthEclipticPrecession.containerObj);
earthEclipticPrecession.pivotObj.add(earthObliquityPrecession.containerObj);
earthObliquityPrecession.pivotObj.add(earthPerihelionPrecession1.containerObj);
earthPerihelionPrecession1.pivotObj.add(earthPerihelionPrecession2.containerObj);
earthPerihelionPrecession2.pivotObj.add(barycenterSun.containerObj);
barycenterSun.pivotObj.add(earthHelionPoint.containerObj);

The calculation chain:

1. Earth → Sets Inclination Precession (333,888 ÷ 3 years)
2. Inclination Precession → Sets Ecliptic Precession (333,888 ÷ 5 years)
3. Ecliptic Precession → Sets Obliquity cycle (333,888 ÷ 8 years)
4. Obliquity cycle → Sets Perihelion Precession (first pass)
5. Perihelion Precession 1 → Sets Perihelion Precession (second pass)
6. Perihelion Precession 2 → Sets Sun Barycenter location
7. Barycenter Sun → Sets PERIHELION-OF-EARTH location

The cumulative effect produces the Axial Precession duration of 333,888 ÷ 13 years around the EARTH-WOBBLE-CENTER.

Configuration Settings

Mean Solar Year Length

The solar year length is calculated from the Holistic-Year:

meanSolarYearLengthInDays = Math.round(365.2421897 * (333888/16)) / (333888/16);

Earth Variables

The Earth object contains all settings for Earth’s orbit around the EARTH-WOBBLE-CENTER:

{
  "name": "Earth",
  "size": (12756.27 / 149597870.698828) * 100,           // Diameter relative to AU
  "speed": -Math.PI * 2 / (333888/13),                   // Axial precession speed
  "rotationSpeed": Math.PI * 2 * (365.242188997508 + 1), // Daily rotation
  "tilt": -23.41398,                                     // Mean axial tilt
  "orbitRadius": -0.0014226 * 100                        // Eccentricity amplitude
}

Inclination Precession

{
  "name": "Earth Inclination Precession",
  "startPos": ((balancedYear - startYear) / (333888/3) * 360),
  "speed": Math.PI * 2 / (333888/3)
}

The startPos is calculated from the Balanced Year (-301,340 BC). This is when the solstice aligned with the PERIHELION-OF-EARTH while the Inclination Tilt and Axial Tilt were exactly opposite - a perfectly balanced state.

Ecliptic Precession

{
  "name": "Earth Ecliptic Precession",
  "startPos": ((balancedYear - startYear) / (333888/5) * 360),
  "speed": Math.PI * 2 / (333888/5),
  "orbitTiltb": -0.634                              // Tilt amplitude (negative)
}

The orbitTiltb value of -0.634° is opposite to the Obliquity cycle’s value of +0.634°. These opposing tilts combine to produce the total obliquity variation.

Obliquity Cycle

{
  "name": "Earth Obliquity Precession",
  "startPos": -((balancedYear - startYear) / (333888/8) * 360),
  "speed": -Math.PI * 2 / (333888/8),
  "orbitTiltb": 0.634                               // Tilt amplitude (positive)
}

Note the negative startPos and speed - this cycle runs opposite to the Ecliptic Precession, creating the combined obliquity effect.

How the Two Tilts Work in the 3D Scene

Each object created by createPlanet builds four nested Three.js containers:

containerObj   →  rotation.x = orbitTilta, rotation.z = orbitTiltb  (FIXED tilt)
                  position = (orbitCentera, orbitCenterc, orbitCenterb)  (FIXED offset)
  └── orbitObj →  rotation.y = θ(t)  (ANIMATED by moveModel each frame)
        ├── pivotObj       (children attach here via hierarchy wiring)
        └── rotationAxis   (axial tilt + spin)
              └── planetObj  (visible mesh)

Note: pivotObj and rotationAxis are siblings under orbitObj, not parent-child. The hierarchy wiring (.add() calls) attaches child objects to pivotObj. The visual mesh lives under rotationAxis.

The containerObj properties are permanent — tilts and position offset are set once at creation and never change. The orbitTiltb tilt physically tips the orbital plane. Because children attach to the pivotObj (inside the orbitObj), the parent’s animated Y-rotation carries the child’s tilt direction around as it sweeps. This is the core mechanism: a fixed tilt whose direction is swept by the parent’s orbital rotation.

What each tilt does in the Earth frame:

The Ecliptic Precession tilt (-A) sits inside the Inclination Precession orbitObj, which rotates at H/3. So this tilt direction is swept around at the H/3 rate (one full revolution per 111,296 years).

The Obliquity Precession tilt (+A) sits one level deeper — inside both the Inclination Precession (H/3) and the Ecliptic Precession (H/5) orbitObjs. Both parent rotations carry its tilt direction, so the net sweep rate is 3 + 5 = 8 → one revolution per H/8 = 41,736 years.

How this creates the obliquity cycle:

Earth’s spin axis is defined by rotationAxis.rotation.z = -23.41° at the earth level — outside the precession hierarchy. It is fixed in the Earth frame.

The two tilts create two rotating perturbations to the orbital plane normal. As each tilt direction sweeps past the spin axis, it alternately increases and decreases the angle between the spin axis and the orbital plane — the obliquity.

• The ecliptic tilt (-A) sweeps at H/3 → produces a slow obliquity oscillation with period H/3
• The obliquity tilt (+A) sweeps at H/8 → produces the ~41,000-year Milankovitch obliquity signal

The combined effect on the obliquity is the sum of these two projections onto the spin axis direction: mean − A·cos(H/3) + A·cos(H/8).

When both components reinforce (both cosines at -1), the obliquity reaches its maximum of ~24.68°. When both oppose (both cosines at +1), it reaches its minimum of ~22.15°. The total range is ±2A = ±1.27°.

How this creates the inclination oscillation:

The inclination to the invariable plane depends on the combined magnitude and direction of the two tilts. The parent Inclination Precession container (H/3) precesses the ascending node direction at H/3. The analytical formula captures this as: mean − A·cos(H/3).

The Fibonacci identity at work: the two tilt rates (H/5 and H/8) and the inclination precession rate (H/3) satisfy 3 + 5 = 8. This identity is why the obliquity tilt’s net sweep rate (3 + 5 = 8) lands exactly on the Fibonacci number 8, producing the H/8 obliquity cycle from components at H/3 and H/5.

Perihelion Precession (Two Parts)

The Perihelion Precession is applied twice with opposite values:

Part 1:

{
  "name": "Earth Perihelion Precession1",
  "startPos": ((balancedYear - startYear) / (333888/16) * 360),
  "speed": Math.PI * 2 / (333888/16),
  "orbitTilta": -1.26                               // RA correction angle
}

Part 2:

{
  "name": "Earth Perihelion Precession2",
  "startPos": -((balancedYear - startYear) / (333888/16) * 360),
  "speed": -Math.PI * 2 / (333888/16),
  "orbitCentera": -0.015321 * 100                   // Base eccentricity
}

How the counter-rotation works in the 3D scene:

This uses the same “sandwich” principle as the two tilts, but for position instead of tilt:

earthPerihelionPrecession1.containerObj  (orbitTilta = -earthRAAngle)
  └── orbitObj rotates at +H/16 (prograde)
        └── earthPerihelionPrecession2.containerObj  (orbitCentera = -eccentricityBase × 100)
              └── orbitObj rotates at -H/16 (retrograde, cancels the prograde)
                    └── barycenterEarthAndSun, PERIHELION-OF-EARTH, Sun

The base eccentricity offset (orbitCentera = -0.015321 × 100) is a fixed position on PerihelionPrecession2’s containerObj. It sits inside PerihelionPrecession1’s orbitObj, which rotates at +H/16. So the offset is swept around at the perihelion precession rate — this IS the perihelion direction precessing.

PerihelionPrecession2’s orbitObj then counter-rotates at -H/16, canceling the precession for everything inside. The Sun, Barycenter, and PERIHELION-OF-EARTH orbit in the correct non-precessing frame, but they are positioned at the eccentricity offset that sweeps with the perihelion.

The Barycenter Sun adds the eccentricity variation (amplitude = 0.0014226 × 100) on top of the base eccentricity:

{
  "name": "Barycenter Sun",
  "orbitRadius": 0.0014226 * 100                    // Eccentricity amplitude
}

Together, the base offset (sweeping with perihelion) plus the amplitude create the full eccentricity cycle: the distance from Earth to the EARTH-WOBBLE-CENTER varies between (base - amplitude) and (base + amplitude) as the perihelion precesses.

The PERIHELION-OF-EARTH is a placeholder object at the Barycenter Sun position to prevent complex Barycenter calculations from interfering with planet position calculations.

The Balanced Year:

const balancedYear = 1246 - (14.5 * (333888/16));  // = -301,340 BC

This represents 14.5 Perihelion Precession cycles before 1246 AD, aligned to explain the obliquity-driven temperature cycles.

Sun

{
  "name": "Sun",
  "startPos": 0.28,                                 // Correction for exact solstice time
  "speed": Math.PI * 2,                             // One solar year
  "rotationSpeed": Math.PI * 2 / (365.2422 / 27.32),// Visual rotation (~27.32 days, simplified)
  "tilt": -7.155,                                   // Solar axial tilt
  "orbitRadius": 100                                // 1 AU
}

Phase Alignment: How startPos Works

Every precession object needs to start at the correct position in its cycle at the model start date. The startPos parameter (in degrees) achieves this with a single formula:

startPos = (balancedYear - startYear) / cycleLength × 360

Since the Balanced Year (-301,340 BC) is the reference epoch where all precession cycles are at their zero phase, dividing the elapsed time by the cycle length gives the fractional cycle completed, and multiplying by 360 converts to degrees.

Examples from the configuration:

Retrograde objects negate their startPos:

The negation matches the negative speed of these retrograde layers, ensuring the phase offset is in the correct direction.

How moveModel uses it:

In moveModel(), the startPos is subtracted from the time-evolved angle:

θ = speed × pos − startPos × (π / 180)

At pos = 0 (the model start date), this gives θ = −startPos × (π/180), placing the object at its correct initial phase. As time advances, speed × pos evolves the phase forward (or backward for retrograde objects).

Right Ascension & Declination Calculations

All celestial position values in the simulation are calculated entirely in the browser - no external API calls. The calculations are deterministic based on the current Julian Date.

Step 1: Get World Positions

Each frame, the simulation retrieves the 3D positions of celestial bodies:

earth.rotationAxis.getWorldPosition(EARTH_POS);   // Earth center
sun.planetObj.getWorldPosition(SUN_POS);          // Sun center
obj.planetObj.getWorldPosition(PLANET_POS);       // Current planet

Step 2: Transform to Earth-Equatorial Frame

The planet’s position is converted to Earth’s local coordinate system, which includes the axial tilt and the 90° rotation that starts the simulation at the June Solstice:

LOCAL.copy(PLANET_POS);
earth.rotationAxis.worldToLocal(LOCAL);           // World → Earth frame

The line earth.containerObj.rotation.y = (Math.PI/2) * whichSolsticeOrEquinox applies the 90° rotation so that 0h RA still points at the March Equinox even though the simulation begins at the June Solstice.

Step 3: Convert to Spherical Coordinates

SPHERICAL.setFromVector3(LOCAL);
obj.ra  = SPHERICAL.theta;                        // θ → Right Ascension (radians)
obj.dec = SPHERICAL.phi;                          // φ → Declination (radians)

Since LOCAL is already in the tilted equatorial frame, θ directly gives the RA and φ gives the Declination - no additional trigonometry needed.

Step 4: Format for Display

The raw radians are converted to sexagesimal notation:

obj.raDisplay  = radiansToRa(obj.ra);             // "12h34m56s"
obj.decDisplay = radiansToDec(obj.dec);           // "+12°34′56″"

Why Values Stay Consistent

The updatePositions() function runs after every orbit/precession update. Since it re-projects the current world-space vector into the live-tilted equator of earth.rotationAxis, any changes to Earth’s tilt, precession rate, or date/time are automatically reflected.

How Other Planets Work

Every planet (Mercury through Neptune, plus Pluto, Halley’s comet, and Eros) uses the same counter-rotation sandwich as Earth’s perihelion precession. The hierarchy, using Jupiter as an example:

barycenterEarthAndSun
└── jupiterPerihelionDurationEcliptic1  (prograde, H/5 perihelion precession)
    └── PERIHELION JUPITER              (speed: +2π/yr, perihelion offset)
        └── jupiterPerihelionDurationEcliptic2  (retrograde, -H/5 cancels #1)
            ├── Jupiter Real Perihelion At Sun  (orbit size, inclination tilt, -2π/yr)
            │   └── Jupiter                     (orbital speed, axial tilt, mesh)
            └── Fixed Perihelion At Sun         (fixed perihelion reference, sibling)

The same sandwich principle applies: Ecliptic1 carries the perihelion marker at the precession rate; Ecliptic2 cancels the precession for the orbit inside. The planet orbits the Sun in the correct heliocentric frame, while its perihelion direction precesses independently.

The +2π/yr and −2π/yr layers are the geocentric frame conversion — they make the orbit center revolve with the Sun while letting the planet orbit at its own rate inside.

Orbital inclination is encoded as a static tilt on the RealPerihelionAtSun container, decomposed into two components based on the J2000 ascending node (Ω) and inclination (i):

orbitTilta = i × sin(Ω)     // rotation.x component
orbitTiltb = i × cos(Ω)     // rotation.z component

This orients the orbital plane at the correct angle to the ecliptic. The tilt is fixed at J2000 values — it does not precess in the 3D scene.

Dynamic inclination is computed analytically for all planets:

i(t) = mean + amplitude × cos(Ω(t) - phaseOffset)

where Ω(t) is the ascending node on the invariable plane, precessing at the planet’s perihelion precession rate. As the ascending node sweeps around, the inclination oscillates between (mean - amplitude) and (mean + amplitude). These computed values are displayed in the GUI predictions panel but do not change the 3D orbital tilt.

Key Differences from Earth

Moon

The Moon uses Earth as its center (not the Sun). It has six nested precession layers, following the same containerObj/orbitObj/pivotObj pattern:

earth.pivotObj
└── moonApsidalPrecession              — apsidal precession (~8.85 yr), carries eccentricity offset
    └── moonApsidalNodalPrecession1    — apsidal-nodal beat (~206 days, retrograde)
        └── moonApsidalNodalPrecession2  — cancels beat (prograde, same period)
            └── moonLunarLevelingCyclePrecession  — lunar leveling cycle (retrograde)
                └── moonNodalPrecession          — nodal precession (~18.6 yr, retrograde), carries ecliptic inclination tilt
                    └── moon                     — tropical month orbital speed

The apsidal precession layer carries the orbital eccentricity offset (orbitRadius). The nodal precession layer carries the ecliptic inclination tilt (orbitTilta/orbitTiltb). All intermediate layers are pure rotation layers with zero radius and zero tilt.

The detailed settings for each body are available in the Excel spreadsheet (on request).

3D Scene vs Analytical Formulas

The simulation computes values through two independent channels. Understanding which channel produces which output is important when reading the code.

3D-derived values — computed by reading positions from the scene hierarchy:

The moveModel() function positions all objects each frame. Then updatePositions() reads their world-space coordinates and transforms them into Earth’s equatorial frame to produce:

• RA and Declination for every planet, the Sun, and the camera
• Distances (Earth→planet, Sun→planet, perihelion→planet)

These values emerge from the full 3D geometry — all precession layers, orbital tilts, and eccentricities are encoded in the scene hierarchy and reflected automatically in the output.

Analytical formulas — computed independently from the scene:

Several values are computed by dedicated functions that use the same input constants but do not read the 3D scene:

These functions run on a 10 Hz throttle (not every frame) and feed the GUI predictions panel, year length calculations, and path visualizations. They produce the same numerical results as the 3D geometry — the formulas are the analytical representation of what the nested containers create geometrically.

Update sequence each frame:

Summary

The simulation demonstrates that all precession phenomena emerge from two simple counter-rotating motions:

• Earth around EARTH-WOBBLE-CENTER (clockwise, 333,888 ÷ 13 years)
• PERIHELION-OF-EARTH around Sun (counter-clockwise, 333,888 ÷ 3 years)

Key Takeaways

1. Two base units - 2π for time (1 year), 100 for distance (1 AU)
2. Nested calculations - Each precession builds on the previous in a specific order
3. Counter-rotating motions - Negative speeds (clockwise) vs positive speeds (counter-clockwise)
4. Browser-based calculations - All RA/Dec values computed locally, no external APIs
5. Geocentric frame — The Sun orbits Earth at 2π/year; planets use +2π/−2π layers for the heliocentric-to-geocentric conversion
6. Two computation channels — RA/Dec from 3D scene geometry; obliquity and inclination from analytical formulas
7. Excel parity - All simulation values match the Excel spreadsheet calculations

Return to the Interactive 3D Simulation or explore the Formulas for the complete analytical formulas.