Skip to content

README.md

Latest commit

 

History

History
294 lines (225 loc) · 11.2 KB

README.md

File metadata and controls

294 lines (225 loc) · 11.2 KB

Caelis Engine 3.0

An Astronomical + Astrological Engine for Modern Apps.

Caelis Engine computes real planetary positions using professional-grade algorithms, renders them as a living symbolic instrument, and exposes a full astrological analysis framework — all in a single HTML file with zero dependencies.

→ Live Demo · License · Author

What problem does it solve?

Most astronomical software is either:

  • Too scientific — raw data with no symbolic or contemplative layer
  • Too decorative — beautiful visuals with imprecise or opaque math
  • Too heavy — frameworks, build steps, backends, APIs

Caelis Engine sits at the intersection: mathematically rigorous, symbolically expressive, and radically simple to run.

No npm install. No build step. No server. Open the file. It works.

Symbol → Structure → Simulation

What it does

🌐 Caelis 2D — Real-time Sky Instrument

  • Computes Sun, Moon, and all classical planets using VSOP87B (planets) and ELP/MPP02-LLR (Moon)
  • Renders a real-time 2D sky map with horizon, ecliptic, house cusps, Milky Way, and 600 background stars
  • Galactic coordinates: accurate Milky Way band using IAU pole transformation
  • Day/night cycle: organic sky gradient anchored to the real Sun position
  • Aspect lines: active conjunctions, oppositions, trines, squares, sextiles with glow
  • Perimeter glow: visual encoding of active aspects, natal transits, and eclipses
  • Click/tap any planet, star, sign, or aspect to open a detailed modal

🔭 Armilar — 3D Celestial Sphere

  • Three.js orbital sphere where planets move in true RA/Dec coordinates from the engine
  • Armilar Mode: toggle real positions vs. artistic free-orbit, with animated blend
  • Configurable visual layers: Ecliptic, Equator, Horizon, Meridian, Dec grid
  • Logarithmic vs. uniform radial scale (orbital proportions)
  • 6 color palettes · Configurable trails and glow
  • Transformare Astralis: cinematic transition ritual between 2D and 3D modes

⊕ Astrolabe — Stereographic Projection

  • Classical astrolabe rendering: Tympanum (horizon, almucantars, azimuths) + Rete (ecliptic, stars, planet pointers)
  • Limbo with 360° graduation
  • Planets positioned as astrolabe pointers on the ecliptic ring

☊ Atacir — Predictive Analysis

  • Primary directions (Al-Biruni / Ptolemy / Naibod) by oblique ascension
  • Natal aspects with exactitude bars and orb classification
  • Transit aspects overlaid on natal chart
  • Synastry (cross-aspects between two charts, house overlay, antiscia)
  • Planetary cycles, return analysis, resonance detection
  • Lunar analysis: phases, perigee/apogee (Meeus Ch.50), nodal returns
  • Export to JSON and plain text

☽ Panchanga — Vedic Almanac

  • Lahiri Ayanamsa (IAU 1955, 2nd-order precession)
  • All 5 elements: Tithi, Vara, Nakshatra (27), Yoga (27), Karana
  • Real-time countdown to next change for each element

⊗ Eclipse Calculator

  • Solar and lunar eclipses using Meeus Ch.54
  • Total, annular, partial classification
  • Geolocation-aware visibility
  • Click any eclipse row to jump the engine to that exact moment

⊞ Ephemeris Dashboard

  • Full real-time table: ecliptic λ/β, RA/Dec, altitude, azimuth, distance (AU), angular velocity (°/day)
  • Rise/Set times with Meeus Ch.15 3-point interpolation + ΔT correction
  • Sidereal time (GST/LST), obliquity, ΔT

🗺️ Natal Chart — SVG Renderer

  • Full SVG wheel with zodiac band, house cusps, aspect lines
  • Bi-wheel for synastry (two charts concentric)
  • Exportable as SVG/PNG
  • Essential dignities: domicile, exaltation, detriment, fall
  • Elemental and modal distribution

Why it's different

Feature Caelis Engine 3.0 Typical astro library Typical sky app
VSOP87B + ELP/MPP02-LLR ✓ sometimes rarely
IAU 2000B Nutation ✓ rarely no
Verified against JPL Horizons ✓ rarely no
Zero dependencies ✓ no no
Symbolic + scientific layer ✓ no no
Panchanga / Vedic almanac ✓ rarely no
Synastry + Atacir directions ✓ rarely no
Eclipse calculator (Meeus 54) ✓ rarely no
Armilar 3D (real RA/Dec) ✓ no no
Astrolabe stereographic ✓ no no
Single file, runs in browser ✓ no no

Precision

All results verified — 30/30 tests PASS (validation.html).

Moon · ELP/MPP02-LLR (Meeus Example 47.a · JDE 2448724.5)

Quantity Computed Meeus reference Error
λ Ecliptic longitude 133.1782° 133.1627° 0.016°
β Ecliptic latitude −3.2286° −3.2291° 0.001°
Δ Geocentric distance 368,436 km 368,409.7 km 27 km

Sun · VSOP87B (Meeus Cap.25)

Date Computed Reference Error
1992-10-13 (Libra) 199.9068° 199.906° < 0.001°
1992-04-12 (Taurus) 22.3402° 22.340° < 0.001°

Planets · JPL Horizons (2026-03-08 12:00 UTC)

Planet Computed JPL Horizons Error
Venus 2.5469° 2.5500° 0.003°
Mars 334.6487° 334.6500° 0.001°
Jupiter 105.0983° 105.1000° 0.002°
Saturn 2.6230° 2.6200° 0.003°

Other components

Component Result
IAU 2000B Nutation ΔΨ < 1 mas vs Meeus
IAU 2006 Obliquity ε < 0.002° vs Meeus
Lahiri Ayanamsa (2nd order) Lieske 1977 precession integration
Lunar phases (JDE) error < 0.17 days vs Meeus Ch.49
Placidus cusps Newton-Raphson iteration, 12/12 correct
Lunar nodes 15-term series, Meeus Ch.47
Eclipse detection Meeus Ch.54, solar + lunar
Rise/Set times 3-point interpolation + ΔT correction

Valid range: 1800–2100 CE at full precision.

Quickstart

git clone https://github.com/HermeticaLabs/caelis-engine
# Open index.html in any modern browser
# No install. No build. No server required.

Or use the JavaScript API directly:

// All computation happens inside index.html — expose via AstroSync
const snap = window.AstroSync.getSnapshot();

console.log(snap.bodies.Sol.lon_ecl);    // Sun ecliptic longitude
console.log(snap.bodies.Luna.lon_ecl);   // Moon ecliptic longitude
console.log(snap.houses.asc);            // Ascendant
console.log(snap.luna.illumination);     // Moon illumination 0–1

// Compute for any moment and location
const historical = window.AstroSync.getSnapshotAt(
  2451545.0,   // JDE (J2000.0)
  -33.45,      // latitude
  -70.66       // longitude
);

Run the precision test suite:

# Serve locally and open validation.html
npx serve .
# → http://localhost:3000/validation.html

Architecture

caelis-engine/
├── index.html              ← Caelis Engine 3.0 — full instrument (zero deps)
├── validation.html         ← Precision test suite — 30/30 PASS
├── caelis_engine_1_5.html  ← Legacy v1.5 (archived)
└── src/
    ├── astro/
    │   └── AstroCore.js    ← VSOP87B, ELP/MPP02, IAU 2000B, coordinate transforms
    ├── TimeEngine.js       ← Julian dates, ΔT, sidereal time, time control
    └── Atacir.js           ← Directions, aspects, cycles, resonances, Panchanga

Key modules inside index.html

Astronomical kernel

  • sunPosition() — VSOP87B + nutation + aberration + light-time
  • moonPosition() — ELP/MPP02-LLR (164L + 105B + 60R terms) + topocentric parallax
  • planetPosition(name) — VSOP87B for Mercury, Venus, Mars, Jupiter, Saturn
  • lunarNodes() — 15-term series (Meeus Ch.47)
  • nutation(T) — IAU 2000B (77 luni-solar terms)
  • deltaT(jd) — Extended table 500–2150 CE + Morrison & Stephenson extrapolation

Analysis

  • calcAtacirCore() — Primary directions (oblique ascension method)
  • calcPanchangaCore() — Full Panchanga with Lahiri ayanamsa
  • calcEclipsesCore() — Solar/lunar eclipse detection (Meeus Ch.54)
  • calcSinastriaCore() — Cross-chart aspects with symbolic weighting
  • getSnapshotAt(jd, lat, lon) — Full ephemeris for any moment/location

Rendering

  • draw() — 2D sky canvas (Canvas API)
  • drawAstrolabio() — Stereographic projection (tympanum + rete)
  • renderOculus() — 3D Armilar sphere (Three.js r128)
  • _cartaRenderSVG() — Natal chart SVG wheel
  • _cartaRenderBiwheel() — Synastry bi-wheel SVG

Mathematical Foundations

  • Jean Meeus — Astronomical Algorithms, 2nd ed.
  • VSOP87B — Bretagnon & Francou (1987), IMCCE
  • ELP/MPP02 — Chapront & Francou (2002), A&A 412 — calibrated with LLR data
  • IAU 2000B — Mathews, Herring & Buffett (2002), IERS Conventions 2003 §5.4
  • IAU 2006 Obliquity — Capitaine et al. (2006)
  • Lahiri Ayanamsa — IAU 1955 + Lieske (1977) 2nd-order precession
  • Atacir — Al-Biruni / Ptolemy / Naibod oblique ascension method
  • ΔT table — Morrison & Stephenson (2004), IERS Bulletins, USNO Circular 179

Changelog

v3.0 (2026-04-11)

  • Armilar 3D Mode: real RA/Dec positioning, configurable layers (ecliptic, equator, horizon, meridian, Dec grid), logarithmic/uniform radial scale, 6 palettes, animated blend real ↔ free
  • Astrolabe: full stereographic projection with tympanum + rete
  • Ephemeris Dashboard: complete real-time table with rise/set (Meeus Ch.15 + ΔT)
  • Natal Chart SVG: full wheel renderer + synastry bi-wheel, exportable
  • Eclipse Calculator: Meeus Ch.54 solar/lunar, geolocation visibility, jump-to feature
  • Panchanga: all 5 elements, 2nd-order Lahiri ayanamsa, real-time countdowns
  • Synastry: cross-aspects, house overlay, antiscia, symbolic weighting
  • IAU 2000B nutation replacing IAU 1980 (< 1 mas accuracy)
  • ELP/MPP02-LLR replacing ELP2000 (LLR-calibrated coefficients)
  • VSOP87B Mercury (122 terms) replacing simplified equation of center
  • ΔT extended table 500–2150 CE
  • Rise/Set: 3-point interpolation + ΔT correction (< 1 min accuracy)
  • Perimeter glow system (aspects, natal transits, eclipses)
  • i18n: ES/EN with full string tables
  • Freemium license system with SHA-256 key validation + device fingerprint

v2.2 (2026-03-01)

  • IAU 2000B nutation (transition)
  • Panchanga (Tithi + Vara free tier)
  • Sinastry core
  • Eclipse calculations (Meeus Ch.54)
  • Expanded ELP/MPP02 lunar terms

v1.5 (2026-01-15)

  • Initial public release
  • VSOP87 planets, ELP2000 Moon
  • 2D sky map, horizon, Placidus houses
  • Atacir primary directions
  • Validation suite (30/30)

License

Caelis Engine is dual-licensed:

Open Source — AGPL-3.0 Free to use, study, modify and share. If you use Caelis Engine in a product or service, you must publish your source code under the same terms.

Commercial License — Hermetica Labs For use in proprietary products or services without the AGPL source disclosure requirement. Contact: hermeticalabs.dev@proton.me

Author

Cristian Valeria Bravo · Hermetica Labs

Caelis Engine exists at the boundary between mathematical precision and symbolic observation — where the structure of time becomes navigable.

© 2024–2026 Cristian Valeria Bravo / Hermetica Labs