celestial-mechanics

name	celestial-mechanics
description	Bridge astronomy-engine and Three.js for solar-system visualizations — positions, orbits, rotations, phases, and coordinate transforms.

Celestial Mechanics for Three.js

Use this skill when working with real astronomy data from astronomy-engine inside a Three.js scene: positioning planets and moons, applying axial tilts, computing phase angles, or converting coordinate systems.

Coordinate Systems

• J2000 Equatorial (EQJ): default output of Astronomy.HelioVector().
• Ecliptic: orbital plane of Earth; convert with Astronomy.Ecliptic(v).
• Three.js: Y-up, right-handed. The project maps the ecliptic plane to Three.js's XZ plane: ecliptic (x, y, z) becomes Three.js (x, z, -y). This places the orbital plane flat on the XZ plane with Y as "up" out of the plane.

// astronomy-engine Vector to Three.js Vector3 in scene units
// (matches main.js:108-111 and main.js:857-859)
const AU_TO_VISUAL = 20; // project-specific scale; project currently uses 22
const pos = new THREE.Vector3(v.x, v.z, -v.y).multiplyScalar(AU_TO_VISUAL);

Observer-local coordinates: Astronomy.Horizon(date, observer, ra, dec, refraction) is available when you need altitude/azimuth for a specific location on Earth.

Positioning Planets

const AU_TO_VISUAL = 20; // project currently uses 22
const ASTRONOMY_TIME_THRESHOLD_MS = 1000 * 60 * 60; // recompute once per simulated hour

let lastSimDate = null;
let cachedPositions = new Map();

function shouldUpdate(simDate) {
  if (!lastSimDate) return true;
  return Math.abs(simDate.getTime() - lastSimDate.getTime()) >= ASTRONOMY_TIME_THRESHOLD_MS;
}

function getHelioPosition(bodyName, simDate) {
  if (shouldUpdate(simDate)) {
    cachedPositions.clear();
    lastSimDate = simDate;
  }
  if (!cachedPositions.has(bodyName)) {
    const vec = Astronomy.HelioVector(bodyName, simDate);
    const ecl = Astronomy.Ecliptic(vec);
    // Ecliptic plane -> Three.js XZ plane (see main.js:108-111, main.js:857-859)
    cachedPositions.set(bodyName, new THREE.Vector3(ecl.vec.x, ecl.vec.z, -ecl.vec.y).multiplyScalar(AU_TO_VISUAL));
  }
  return cachedPositions.get(bodyName);
}

Positioning Moons

Earth's Moon

const geoMoon = Astronomy.GeoMoon(simDate);
const ecl = Astronomy.Ecliptic(geoMoon);
const angle = Math.atan2(ecl.vec.y, ecl.vec.x);
moonOrbitContainer.rotation.y = -angle; // match Three.js rotation direction

Jupiter's Moons

const jupiterMoons = Astronomy.JupiterMoons(simDate);
const io = jupiterMoons.io;
const ecl = Astronomy.Ecliptic(io);
const angle = Math.atan2(ecl.vec.y, ecl.vec.x);
ioContainer.rotation.y = -angle;

Axial Tilt and Rotation

// Parent container holds the tilt
const tiltContainer = new THREE.Object3D();
// Three.js r128 renamed THREE.Math to THREE.MathUtils
tiltContainer.rotation.z = THREE.MathUtils.degToRad(obliquityDegrees);
scene.add(tiltContainer);

// Mesh spins inside the container
const mesh = new THREE.Mesh(geometry, material);
tiltContainer.add(mesh);
mesh.rotation.y += rotationSpeed * deltaTime;

// Retrograde rotation (Venus, Uranus)
mesh.rotation.y -= rotationSpeed * deltaTime;

Tidal Locking

// Keep the same face toward the parent planet.
// This is the simplified form for moons orbiting in the XZ plane;
// for inclined/elliptical orbits, derive the look-at from the parent.
moonMesh.rotation.y = -moonOrbitContainer.rotation.y;

Phase Calculations

// Sun direction in Moon's local space for shaders.
// Sun is at world origin; transform that point into Moon's local space.
// The result is the vector from the Moon's center to the Sun, which we normalize.
const sunLocal = new THREE.Vector3(0, 0, 0);
moonMesh.worldToLocal(sunLocal);
moonPhaseMaterial.uniforms.sunDirection.value.copy(sunLocal).normalize();

// Phase angle for the Moon (project uses this pattern at main.js:2032-2035)
const illum = Astronomy.Illumination('Moon', simDate);
const phaseAngleRad = illum.phase_angle * Math.PI / 180.0;
// phase_angle = 0° means full Moon, 180° means new Moon

// For named/integer phases you can also use:
const phaseName = Astronomy.MoonPhase(simDate); // e.g. Astronomy.Phase.New, FirstQuarter, etc.

Visual Scaling

// Typical project scales
const AU_TO_VISUAL = 20;
const SUN_RADIUS_VISUAL = 5.5;
const EARTH_RADIUS_VISUAL = 0.5;

// Preserve relative proportions while staying visible
function scaledRadius(realRadiusKm, referenceKm, referenceVisual) {
  return (realRadiusKm / referenceKm) * referenceVisual;
}

Common Pitfalls

• Confusing ecliptic vs equatorial outputs from astronomy-engine.
• Forgetting that Three.js rotation direction is opposite to astronomy-engine angle sign.
• Passing a raw JavaScript Date where astronomy-engine expects an internal time object, or vice versa.
• Failing to invalidate cached positions when the simulated date jumps backward or forward rapidly.
• Treating directions and points the same way when transforming into local object space.

See Also

• threejs / threejs-fundamentals / threejs-shaders — Three.js specifics
• web-design-guidelines / frontend-design — UI and visual design
• astronomy-engine documentation