Skip to content

Commit 52afcb6

Browse files
HermeticaLabsHermeticaLabs
committed
docs: README Caelis Engine 3.0
1 parent 9cbd03e commit 52afcb6

1 file changed

Lines changed: 62 additions & 254 deletions

File tree

‎README.md‎

Lines changed: 62 additions & 254 deletions
Original file line numberDiff line numberDiff line change
@@ -1,294 +1,102 @@
1-
# Caelis Engine 3.0
1+
# ⊛ Caelis Engine 3.0
22

3-
**An Astronomical + Astrological Engine for Modern Apps.**
3+
**Motor astronómico contemplativo — Hermetica Labs**
44

5-
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**.
6-
7-
[**→ Live Demo**](https://hermeticalabs.github.io/caelis-engine) · [**License**](#license) · [**Author**](#author)
5+
Caelis Engine es un instrumento astronómico de alta precisión ejecutado completamente en el navegador, sin dependencias de servidor. Combina cálculo astronómico riguroso (VSOP87, ELP/MPP02, IAU 2000B) con una interfaz contemplativa diseñada para la observación y el estudio del cielo.
86

97
---
108

11-
## What problem does it solve?
12-
13-
Most astronomical software is either:
14-
15-
- **Too scientific** — raw data with no symbolic or contemplative layer
16-
- **Too decorative** — beautiful visuals with imprecise or opaque math
17-
- **Too heavy** — frameworks, build steps, backends, APIs
18-
19-
Caelis Engine sits at the intersection: **mathematically rigorous, symbolically expressive, and radically simple to run.**
9+
## Uso
2010

21-
No npm install. No build step. No server. Open the file. It works.
11+
Abre `caelis_engine_3_0.html` directamente en el navegador. No requiere instalación ni servidor.
2212

2313
```
24-
Symbol → Structure → Simulation
14+
caelis_engine_3_0.html ← instrumento completo, autocontenido
2515
```
2616

2717
---
2818

29-
## What it does
30-
31-
### 🌐 Caelis 2D — Real-time Sky Instrument
32-
- Computes Sun, Moon, and all classical planets using **VSOP87B** (planets) and **ELP/MPP02-LLR** (Moon)
33-
- Renders a real-time **2D sky map** with horizon, ecliptic, house cusps, Milky Way, and 600 background stars
34-
- **Galactic coordinates**: accurate Milky Way band using IAU pole transformation
35-
- **Day/night cycle**: organic sky gradient anchored to the real Sun position
36-
- **Aspect lines**: active conjunctions, oppositions, trines, squares, sextiles with glow
37-
- **Perimeter glow**: visual encoding of active aspects, natal transits, and eclipses
38-
- Click/tap any planet, star, sign, or aspect to open a detailed modal
39-
40-
### 🔭 Armilar — 3D Celestial Sphere
41-
- Three.js orbital sphere where planets move in **true RA/Dec coordinates** from the engine
42-
- **Armilar Mode**: toggle real positions vs. artistic free-orbit, with animated blend
43-
- Configurable visual layers: Ecliptic, Equator, Horizon, Meridian, Dec grid
44-
- Logarithmic vs. uniform radial scale (orbital proportions)
45-
- 6 color palettes · Configurable trails and glow
46-
- **Transformare Astralis**: cinematic transition ritual between 2D and 3D modes
47-
48-
### ⊕ Astrolabe — Stereographic Projection
49-
- Classical astrolabe rendering: **Tympanum** (horizon, almucantars, azimuths) + **Rete** (ecliptic, stars, planet pointers)
50-
- Limbo with 360° graduation
51-
- Planets positioned as astrolabe pointers on the ecliptic ring
52-
53-
### ☊ Atacir — Predictive Analysis
54-
- **Primary directions** (Al-Biruni / Ptolemy / Naibod) by oblique ascension
55-
- Natal aspects with exactitude bars and orb classification
56-
- Transit aspects overlaid on natal chart
57-
- Synastry (cross-aspects between two charts, house overlay, antiscia)
58-
- Planetary cycles, return analysis, resonance detection
59-
- Lunar analysis: phases, perigee/apogee (Meeus Ch.50), nodal returns
60-
- Export to JSON and plain text
61-
62-
### ☽ Panchanga — Vedic Almanac
63-
- **Lahiri Ayanamsa** (IAU 1955, 2nd-order precession)
64-
- All 5 elements: Tithi, Vara, Nakshatra (27), Yoga (27), Karana
65-
- Real-time countdown to next change for each element
66-
67-
### ⊗ Eclipse Calculator
68-
- Solar and lunar eclipses using **Meeus Ch.54**
69-
- Total, annular, partial classification
70-
- Geolocation-aware visibility
71-
- Click any eclipse row to jump the engine to that exact moment
72-
73-
### ⊞ Ephemeris Dashboard
74-
- Full real-time table: ecliptic λ/β, RA/Dec, altitude, azimuth, distance (AU), angular velocity (°/day)
75-
- **Rise/Set times** with Meeus Ch.15 3-point interpolation + ΔT correction
76-
- Sidereal time (GST/LST), obliquity, ΔT
77-
78-
### 🗺️ Natal Chart — SVG Renderer
79-
- Full SVG wheel with zodiac band, house cusps, aspect lines
80-
- **Bi-wheel** for synastry (two charts concentric)
81-
- Exportable as SVG/PNG
82-
- Essential dignities: domicile, exaltation, detriment, fall
83-
- Elemental and modal distribution
84-
85-
---
86-
87-
## Why it's different
88-
89-
| Feature | Caelis Engine 3.0 | Typical astro library | Typical sky app |
90-
|---|---|---|---|
91-
| VSOP87B + ELP/MPP02-LLR | ✓ | sometimes | rarely |
92-
| IAU 2000B Nutation | ✓ | rarely | no |
93-
| Verified against JPL Horizons | ✓ | rarely | no |
94-
| Zero dependencies | ✓ | no | no |
95-
| Symbolic + scientific layer | ✓ | no | no |
96-
| Panchanga / Vedic almanac | ✓ | rarely | no |
97-
| Synastry + Atacir directions | ✓ | rarely | no |
98-
| Eclipse calculator (Meeus 54) | ✓ | rarely | no |
99-
| Armilar 3D (real RA/Dec) | ✓ | no | no |
100-
| Astrolabe stereographic | ✓ | no | no |
101-
| Single file, runs in browser | ✓ | no | no |
102-
103-
---
104-
105-
## Precision
106-
107-
All results verified — **30/30 tests PASS** (`validation.html`).
108-
109-
### Moon · ELP/MPP02-LLR (Meeus Example 47.a · JDE 2448724.5)
110-
111-
| Quantity | Computed | Meeus reference | Error |
112-
|---|---|---|---|
113-
| λ Ecliptic longitude | 133.1782° | 133.1627° | **0.016°** |
114-
| β Ecliptic latitude | −3.2286° | −3.2291° | **0.001°** |
115-
| Δ Geocentric distance | 368,436 km | 368,409.7 km | **27 km** |
116-
117-
### Sun · VSOP87B (Meeus Cap.25)
118-
119-
| Date | Computed | Reference | Error |
120-
|---|---|---|---|
121-
| 1992-10-13 (Libra) | 199.9068° | 199.906° | **< 0.001°** |
122-
| 1992-04-12 (Taurus) | 22.3402° | 22.340° | **< 0.001°** |
123-
124-
### Planets · JPL Horizons (2026-03-08 12:00 UTC)
19+
## Arquitectura
12520

126-
| Planet | Computed | JPL Horizons | Error |
127-
|---|---|---|---|
128-
| Venus | 2.5469° | 2.5500° | **0.003°** |
129-
| Mars | 334.6487° | 334.6500° | **0.001°** |
130-
| Jupiter | 105.0983° | 105.1000° | **0.002°** |
131-
| Saturn | 2.6230° | 2.6200° | **0.003°** |
21+
Caelis Engine 3.0 es un **monolito de archivo único** (~540 KB). Todo el motor astronómico, la interfaz, los algoritmos de cálculo y la visualización 3D están contenidos en un solo archivo HTML.
13222

133-
### Other components
23+
### Estructura interna
13424

135-
| Component | Result |
136-
|---|---|
137-
| IAU 2000B Nutation ΔΨ | < 1 mas vs Meeus |
138-
| IAU 2006 Obliquity ε | < 0.002° vs Meeus |
139-
| Lahiri Ayanamsa (2nd order) | Lieske 1977 precession integration |
140-
| Lunar phases (JDE) | error < 0.17 days vs Meeus Ch.49 |
141-
| Placidus cusps | Newton-Raphson iteration, 12/12 correct |
142-
| Lunar nodes | 15-term series, Meeus Ch.47 |
143-
| Eclipse detection | Meeus Ch.54, solar + lunar |
144-
| Rise/Set times | 3-point interpolation + ΔT correction |
25+
```
26+
caelis_engine_3_0.html
27+
├── Motor de tiempo currentTime(), julianDate(), deltaT()
28+
├── Algoritmos planetarios VSOP87B (Mercurio–Saturno), ELP/MPP02 (Luna)
29+
├── Correcciones Nutación IAU 2000B, aberración anual, light-time
30+
├── Correcciones topocéntricas paralaje diurno, refracción atmosférica
31+
├── Módulo Rise/Set Meeus Cap.15, interpolación 3 puntos, ΔT correcto
32+
├── Dashboard de efemérides RA, Dec, Alt, Az, Dist, Vel, Rise, Set
33+
├── Visualización 2D Astrolabio estereográfico, modo Oculus 2D
34+
└── Visualización 3D Three.js (modo reservado)
35+
```
14536

146-
**Valid range:** 1800–2100 CE at full precision.
37+
### Algoritmos de precisión
38+
39+
| Cuerpo | Algoritmo | Precisión |
40+
|--------|-----------|-----------|
41+
| Mercurio | VSOP87B oficial (IMCCE, 122 términos) | ±3" longitud |
42+
| Venus | VSOP87 (Meeus App.II, ~79 términos) | ±5" |
43+
| Tierra | VSOP87 (Meeus App.II, ~185 términos) | ±1" |
44+
| Marte | VSOP87 (Meeus App.II, ~152 términos) | ±15" |
45+
| Júpiter | VSOP87 (Meeus App.II, ~141 términos) | ±30" |
46+
| Saturno | VSOP87 (Meeus App.II, ~167 términos) | ±40" |
47+
| Luna | ELP/MPP02 (164L + 105B + 29R términos) | ±30" longitud |
48+
| Sol | VSOP87 Tierra invertido + nutación + aberración | ±1" |
49+
50+
Correcciones aplicadas a todos los cuerpos:
51+
- Nutación IAU 2000B (Δψ, Δε)
52+
- Aberración anual (Meeus §23)
53+
- Tiempo de luz (light-time, iterativo)
54+
- Corrección topocéntrica (paralaje diurno, RA y Dec)
55+
- ΔT (tabla IERS interpolada, 1900–2030)
56+
57+
### Rise / Set
58+
59+
Implementación Meeus Cap.15 con:
60+
- Interpolación cuadrática de 3 puntos (t−1d, t₀, t+1d)
61+
- ΔT aplicado al GMST (JD UT, no TT)
62+
- 3 iteraciones de corrección de altitud
63+
- h₀ correcto por cuerpo: Sol −50', Luna +7', planetas −34'
64+
- Hora local automática vía `Date.getTimezoneOffset()`
14765

14866
---
14967

150-
## Quickstart
151-
152-
```bash
153-
git clone https://github.com/HermeticaLabs/caelis-engine
154-
# Open index.html in any modern browser
155-
# No install. No build. No server required.
156-
```
157-
158-
Or use the JavaScript API directly:
159-
160-
```javascript
161-
// All computation happens inside index.html — expose via AstroSync
162-
const snap = window.AstroSync.getSnapshot();
68+
## Módulos fuente (referencia)
16369

164-
console.log(snap.bodies.Sol.lon_ecl); // Sun ecliptic longitude
165-
console.log(snap.bodies.Luna.lon_ecl); // Moon ecliptic longitude
166-
console.log(snap.houses.asc); // Ascendant
167-
console.log(snap.luna.illumination); // Moon illumination 0–1
70+
La carpeta `src/` contiene los módulos que fueron la base de desarrollo de versiones anteriores. En v3.0, toda la lógica está consolidada en el monolito.
16871

169-
// Compute for any moment and location
170-
const historical = window.AstroSync.getSnapshotAt(
171-
2451545.0, // JDE (J2000.0)
172-
-33.45, // latitude
173-
-70.66 // longitude
174-
);
17572
```
176-
177-
Run the precision test suite:
178-
179-
```bash
180-
# Serve locally and open validation.html
181-
npx serve .
182-
# → http://localhost:3000/validation.html
73+
src/
74+
├── vsop87/ Coeficientes VSOP87B fuente
75+
├── elp/ Tablas ELP/MPP02
76+
└── utils/ Utilidades de formateo y conversión
18377
```
18478

18579
---
18680

187-
## Architecture
81+
## Tests
18882

18983
```
190-
caelis-engine/
191-
├── index.html ← Caelis Engine 3.0 — full instrument (zero deps)
192-
├── validation.html ← Precision test suite — 30/30 PASS
193-
├── caelis_engine_1_5.html ← Legacy v1.5 (archived)
194-
└── src/
195-
├── astro/
196-
│ └── AstroCore.js ← VSOP87B, ELP/MPP02, IAU 2000B, coordinate transforms
197-
├── TimeEngine.js ← Julian dates, ΔT, sidereal time, time control
198-
└── Atacir.js ← Directions, aspects, cycles, resonances, Panchanga
84+
tests/validation.html Suite de 30 tests contra Meeus y JPL Horizons
19985
```
20086

201-
### Key modules inside `index.html`
202-
203-
**Astronomical kernel**
204-
- `sunPosition()` — VSOP87B + nutation + aberration + light-time
205-
- `moonPosition()` — ELP/MPP02-LLR (164L + 105B + 60R terms) + topocentric parallax
206-
- `planetPosition(name)` — VSOP87B for Mercury, Venus, Mars, Jupiter, Saturn
207-
- `lunarNodes()` — 15-term series (Meeus Ch.47)
208-
- `nutation(T)` — IAU 2000B (77 luni-solar terms)
209-
- `deltaT(jd)` — Extended table 500–2150 CE + Morrison & Stephenson extrapolation
210-
211-
**Analysis**
212-
- `calcAtacirCore()` — Primary directions (oblique ascension method)
213-
- `calcPanchangaCore()` — Full Panchanga with Lahiri ayanamsa
214-
- `calcEclipsesCore()` — Solar/lunar eclipse detection (Meeus Ch.54)
215-
- `calcSinastriaCore()` — Cross-chart aspects with symbolic weighting
216-
- `getSnapshotAt(jd, lat, lon)` — Full ephemeris for any moment/location
217-
218-
**Rendering**
219-
- `draw()` — 2D sky canvas (Canvas API)
220-
- `drawAstrolabio()` — Stereographic projection (tympanum + rete)
221-
- `renderOculus()` — 3D Armilar sphere (Three.js r128)
222-
- `_cartaRenderSVG()` — Natal chart SVG wheel
223-
- `_cartaRenderBiwheel()` — Synastry bi-wheel SVG
224-
225-
---
226-
227-
## Mathematical Foundations
228-
229-
- Jean Meeus — *Astronomical Algorithms*, 2nd ed.
230-
- **VSOP87B** — Bretagnon & Francou (1987), IMCCE
231-
- **ELP/MPP02** — Chapront & Francou (2002), A&A 412 — calibrated with LLR data
232-
- **IAU 2000B** — Mathews, Herring & Buffett (2002), IERS Conventions 2003 §5.4
233-
- **IAU 2006** Obliquity — Capitaine et al. (2006)
234-
- **Lahiri Ayanamsa** — IAU 1955 + Lieske (1977) 2nd-order precession
235-
- **Atacir** — Al-Biruni / Ptolemy / Naibod oblique ascension method
236-
- **ΔT table** — Morrison & Stephenson (2004), IERS Bulletins, USNO Circular 179
87+
Ejecutar: abrir `tests/validation.html` en el navegador.
23788

23889
---
23990

24091
## Changelog
24192

242-
### v3.0 (2026-04-11)
243-
- **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
244-
- **Astrolabe**: full stereographic projection with tympanum + rete
245-
- **Ephemeris Dashboard**: complete real-time table with rise/set (Meeus Ch.15 + ΔT)
246-
- **Natal Chart SVG**: full wheel renderer + synastry bi-wheel, exportable
247-
- **Eclipse Calculator**: Meeus Ch.54 solar/lunar, geolocation visibility, jump-to feature
248-
- **Panchanga**: all 5 elements, 2nd-order Lahiri ayanamsa, real-time countdowns
249-
- **Synastry**: cross-aspects, house overlay, antiscia, symbolic weighting
250-
- **IAU 2000B** nutation replacing IAU 1980 (< 1 mas accuracy)
251-
- **ELP/MPP02-LLR** replacing ELP2000 (LLR-calibrated coefficients)
252-
- **VSOP87B** Mercury (122 terms) replacing simplified equation of center
253-
- **ΔT** extended table 500–2150 CE
254-
- Rise/Set: 3-point interpolation + ΔT correction (< 1 min accuracy)
255-
- Perimeter glow system (aspects, natal transits, eclipses)
256-
- i18n: ES/EN with full string tables
257-
- Freemium license system with SHA-256 key validation + device fingerprint
258-
259-
### v2.2 (2026-03-01)
260-
- IAU 2000B nutation (transition)
261-
- Panchanga (Tithi + Vara free tier)
262-
- Sinastry core
263-
- Eclipse calculations (Meeus Ch.54)
264-
- Expanded ELP/MPP02 lunar terms
265-
266-
### v1.5 (2026-01-15)
267-
- Initial public release
268-
- VSOP87 planets, ELP2000 Moon
269-
- 2D sky map, horizon, Placidus houses
270-
- Atacir primary directions
271-
- Validation suite (30/30)
272-
273-
---
274-
275-
## License
276-
277-
Caelis Engine is dual-licensed:
278-
279-
**Open Source — AGPL-3.0**
280-
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.
281-
282-
**Commercial License — Hermetica Labs**
283-
For use in proprietary products or services without the AGPL source disclosure requirement.
284-
Contact: [hermeticalabs.dev@proton.me](mailto:hermeticalabs.dev@proton.me)
93+
Ver [CHANGELOG.md](CHANGELOG.md) para historial completo de versiones.
28594

28695
---
28796

288-
## Author
289-
290-
**Cristian Valeria Bravo** · [Hermetica Labs](https://github.com/HermeticaLabs)
97+
## Licencia
29198

292-
*Caelis Engine exists at the boundary between mathematical precision and symbolic observation — where the structure of time becomes navigable.*
99+
**CC BY-NC-ND 4.0** — Hermetica Labs
100+
Uso permitido con atribución. No comercial. Sin obras derivadas.
293101

294-
© 2024–2026 Cristian Valeria Bravo / Hermetica Labs
102+
© 2024–2026 Hermetica Labs · [github.com/HermeticaLabs](https://github.com/HermeticaLabs)

0 commit comments

Comments
 (0)