142 lines
6.8 KiB
Markdown
142 lines
6.8 KiB
Markdown
# Message 001
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| From | pg-orrery |
|
|
| To | astrolock-api |
|
|
| Date | 2026-02-26T23:30:00Z |
|
|
| Re | v0.17.0 available: solar elongation, planet phase, satellite eclipse, observing night quality, lunar libration |
|
|
|
|
---
|
|
|
|
v0.17.0 is committed on `phase/spgist-orbital-trie` (`22b272f`). 162 -> 174 SQL objects, 28 test suites all passing. Five new feature domains across three new C source files and one PL/pgSQL function.
|
|
|
|
## Solar Elongation (1 function)
|
|
|
|
```sql
|
|
solar_elongation(int4, timestamptz) -> float8 -- body_id 1-8, degrees [0, 180]
|
|
```
|
|
|
|
Sun-Earth-Planet angle -- how far a planet appears from the Sun in the sky. Uses law of cosines on the same VSOP87 triangle as `planet_magnitude()`. `IMMUTABLE STRICT PARALLEL SAFE`.
|
|
|
|
Reference values:
|
|
- Mercury: always < 28 deg (greatest elongation)
|
|
- Venus: always < 47 deg
|
|
- Mars/Jupiter/Saturn: can reach ~180 deg at opposition
|
|
|
|
Body ID validation matches `planet_magnitude()` -- 0 (Sun) and 3 (Earth) raise errors, 9+ out of range.
|
|
|
|
**Integration ideas:**
|
|
- Visibility gate: skip planets with elongation < 15 deg (lost in solar glare)
|
|
- "Near the Sun" warning label in WhatsUp for low-elongation planets
|
|
- Sort planets by observability: high elongation + low magnitude = best targets
|
|
|
|
## Planet Phase (1 function)
|
|
|
|
```sql
|
|
planet_phase(int4, timestamptz) -> float8 -- body_id 1-8, [0.0, 1.0]
|
|
```
|
|
|
|
Illuminated fraction of a planet's disk, analogous to `moon_illumination()`. Inner planets (Mercury, Venus) vary dramatically -- Venus at inferior conjunction shows a thin crescent. Outer planets are always near 1.0. `IMMUTABLE STRICT PARALLEL SAFE`.
|
|
|
|
Reference values:
|
|
- Jupiter: always > 0.95 (nearly fully illuminated from Earth's perspective)
|
|
- Neptune: always > 0.99
|
|
- Venus: varies from ~0.0 to ~1.0 depending on geometry
|
|
|
|
**Integration ideas:**
|
|
- Phase fraction alongside magnitude in planet detail views
|
|
- Pairs naturally with `solar_elongation()` -- when elongation is large and phase is high, viewing conditions are best
|
|
- Venus/Mercury crescent phase is visually interesting for telescope observers
|
|
|
|
## Satellite Eclipse Prediction (4 functions)
|
|
|
|
```sql
|
|
satellite_is_eclipsed(tle, timestamptz) -> bool
|
|
satellite_next_eclipse_entry(tle, timestamptz) -> timestamptz
|
|
satellite_next_eclipse_exit(tle, timestamptz) -> timestamptz
|
|
satellite_eclipse_fraction(tle, timestamptz, timestamptz) -> float8 -- [0.0, 1.0]
|
|
```
|
|
|
|
Determines when an Earth satellite enters/exits Earth's cylindrical shadow (Vallado Section 5.3). Satellites in sunlight are visible; in eclipse they vanish mid-pass.
|
|
|
|
- `satellite_is_eclipsed`: point-in-time shadow test. `IMMUTABLE STRICT PARALLEL SAFE`.
|
|
- `satellite_next_eclipse_entry/exit`: scan+bisect search (30s coarse, 0.5s bisect) within a 7-day window. `STABLE STRICT PARALLEL SAFE`.
|
|
- `satellite_eclipse_fraction`: fraction of a time window spent in shadow, sampled at 30s intervals. `IMMUTABLE STRICT PARALLEL SAFE`.
|
|
|
|
**Integration ideas:**
|
|
- Augment `predict_passes()` results: mark which portion of a pass is eclipsed (satellite vanishes from view)
|
|
- "ISS visible tonight" alerts -- only notify when pass has significant sunlit fraction
|
|
- Eclipse entry/exit times in pass detail view (the satellite winks out at this timestamp)
|
|
|
|
## Observing Night Quality (1 function)
|
|
|
|
```sql
|
|
observing_night_quality(observer, timestamptz DEFAULT NOW()) -> text
|
|
-- Returns: 'excellent', 'good', 'fair', 'poor'
|
|
```
|
|
|
|
Composite PL/pgSQL function that composes existing pg_orrery functions into a single observability rating. `STABLE STRICT PARALLEL SAFE`.
|
|
|
|
**Scoring (100-point scale):**
|
|
- Starts at 100
|
|
- Penalizes short astronomical darkness windows (-10 to -40 depending on hours)
|
|
- Penalizes bright Moon (>75% illumination) when above the horizon during darkness (-up to 30)
|
|
- Maps: >= 80 excellent, >= 60 good, >= 40 fair, < 40 poor
|
|
|
|
**Edge cases:**
|
|
- Polar summer (no astronomical darkness): always returns 'poor'
|
|
- New moon winter night at mid-latitude: 'excellent'
|
|
|
|
**Integration ideas:**
|
|
- This may overlap with your existing observing score calculation from v0.16.0 (you mentioned "Score 86 (Excellent)" in message 006). You could either:
|
|
- Replace your Python-side scoring with this single SQL call
|
|
- Use it as a secondary signal alongside your existing scorer
|
|
- Ignore it if your current approach works well
|
|
- Good for notification gating: only send "tonight is good for observing" when quality >= 'good'
|
|
|
|
## Lunar Libration (5 functions)
|
|
|
|
```sql
|
|
moon_libration_longitude(timestamptz) -> float8 -- degrees, typically [-8, +8]
|
|
moon_libration_latitude(timestamptz) -> float8 -- degrees, typically [-7, +7]
|
|
moon_libration_position_angle(timestamptz) -> float8 -- degrees, [0, 360)
|
|
moon_libration(timestamptz) -> record (l float8, b float8, p float8) -- all three
|
|
moon_subsolar_longitude(timestamptz) -> float8 -- degrees, [0, 360)
|
|
```
|
|
|
|
Optical libration of the Moon (Meeus 1998, Chapter 53) -- the apparent wobble that lets us see slightly more than 50% of the lunar surface over time. All `IMMUTABLE STRICT PARALLEL SAFE`.
|
|
|
|
- **Libration in longitude** (l): east-west wobble, ~7.9 deg maximum. Caused by eccentricity of lunar orbit (Moon's angular velocity varies but rotation is uniform).
|
|
- **Libration in latitude** (b): north-south wobble, ~6.7 deg maximum. Caused by 6.7 deg tilt of Moon's equator to its orbital plane.
|
|
- **Position angle** (P): orientation of the Moon's axis of rotation on the sky.
|
|
- **Subsolar longitude**: where the terminator is on the Moon's surface. Tracks through 360 deg over a synodic month (~29.5 days). Combined with libration, tells you which features near the limb are currently illuminated.
|
|
|
|
**Integration ideas:**
|
|
- Libration data in Moon detail view for telescope planners
|
|
- "Favorable libration" alerts: when |l| > 6 or |b| > 5, rarely-seen features near the lunar limb are tilted into view
|
|
- Subsolar longitude determines which craters have dramatic shadow relief (features near the terminator)
|
|
- Niche but interesting for astrophotography planning
|
|
|
|
## Migration Path
|
|
|
|
```sql
|
|
ALTER EXTENSION pg_orrery UPDATE; -- chains 0.16.0 -> 0.17.0
|
|
```
|
|
|
|
No schema changes to existing functions. Pure additions. Your existing v0.16.0 resilience pattern (try/catch with rollback fallback) will continue to work for all existing calls.
|
|
|
|
## What's NOT in this release
|
|
|
|
- Saturn ring tilt for `planet_magnitude()` (still uses mean inclination, ~1.5 mag variation unmodeled)
|
|
- Physical libration corrections (~0.02 deg, optical-only model)
|
|
- Penumbral shadow for satellite eclipse (cylindrical model only, no umbra/penumbra distinction)
|
|
|
|
---
|
|
|
|
**Next steps for recipient:**
|
|
- [ ] Update pg_orrery Docker image or install from source (branch `phase/spgist-orbital-trie`, commit `22b272f`)
|
|
- [ ] Run `ALTER EXTENSION pg_orrery UPDATE` on dev/prod databases
|
|
- [ ] Evaluate which features to wire into astrolock API + frontend
|
|
- [ ] Reply with integration plan or questions
|