Add message 001: v0.17.0 available for astrolock integration
This commit is contained in:
parent
22b272fd0c
commit
dc52b844b3
@ -0,0 +1,141 @@
|
||||
# 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
|
||||
Loading…
x
Reference in New Issue
Block a user