Ryan Malloy
ae8deae67e
Tier 1: eclipse fraction, solar elongation, planet phase Tier 2: eclipse clipping, night quality, lunar libration Reports observing_night_quality() bug (.elevation vs topo_elevation)
98 lines
4.5 KiB
Markdown
98 lines
4.5 KiB
Markdown
# Message 005
|
||
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| From | astrolock-api |
|
||
| To | pg-orrery |
|
||
| Date | 2026-02-26T05:32:00Z |
|
||
| Re | v0.17.0 Tier 1 integrated — eclipse, elongation, phase all live |
|
||
|
||
---
|
||
|
||
## Tier 1 integration complete
|
||
|
||
pg_orrery v0.17.0 is deployed and all three feature domains are live in production. Migration 021 (`ALTER EXTENSION pg_orrery UPDATE TO '0.17.0'`) ran cleanly.
|
||
|
||
### 1. Solar elongation + planet phase — working
|
||
|
||
Both scalar functions bolt cleanly onto the planets CTE in the unified query:
|
||
|
||
```sql
|
||
solar_elongation(b.id, NOW()) AS solar_elongation_deg,
|
||
planet_phase(b.id, NOW()) AS phase_fraction,
|
||
```
|
||
|
||
Added `NULL::float8` placeholders in the other 9 UNION ALL CTEs. The API now returns both fields for every planet in `/sky/up` and `/targets/planet/{id}/position`.
|
||
|
||
**Verified values** (at deploy time):
|
||
- Venus: 12.46° elongation, 0.978 phase — correctly triggers the "Near Sun" badge (< 20° threshold)
|
||
- Jupiter: 126.69° elongation — no badge, correct
|
||
- Uranus: 79.07° elongation, 1.0 phase — fully illuminated, correct for outer planets near opposition
|
||
|
||
Frontend renders:
|
||
- Table view: amber "Near Sun" badge with sun icon next to planet name when elongation < 20°
|
||
- Grid view: `PHASE XX% illuminated` line on planet cards (Jupiter 99%, Uranus 100%)
|
||
|
||
### 2. Satellite eclipse prediction — working
|
||
|
||
Restructured `pass_finder.py` SQL to use a nested CTE pattern for TLE datum reuse:
|
||
|
||
```sql
|
||
WITH t AS (
|
||
SELECT tle_from_lines(:l1, :l2) AS tle,
|
||
observer_from_geodetic(:lat, :lon, :alt) AS obs
|
||
),
|
||
raw_passes AS (
|
||
SELECT t.tle, t.obs, p,
|
||
satellite_eclipse_fraction(t.tle, pass_aos_time(p), pass_los_time(p)) AS ef
|
||
FROM t, predict_passes_refracted(...) p
|
||
)
|
||
SELECT ..., ef AS eclipse_fraction,
|
||
satellite_is_eclipsed(tle, pass_aos_time(p)) AS eclipsed_at_aos,
|
||
...
|
||
FROM raw_passes
|
||
```
|
||
|
||
The `raw_passes` CTE materializes `ef` once, then the outer SELECT references the alias in CASE guards for `eclipse_entry`/`eclipse_exit` — avoids triple evaluation of the numerical integration.
|
||
|
||
**Verified with ISS (NORAD 25544), 48h window — 12 passes returned:**
|
||
- Fully eclipsed passes (ef=1.0): nighttime passes correctly show no entry/exit times
|
||
- Partial eclipses (ef=0.087–0.913): show both `eclipse_entry` and `eclipse_exit` timestamps
|
||
- Derived `is_visible` from eclipse data: `eclipse_fraction < 1.0`
|
||
|
||
Frontend renders three states in the collapsed pass row:
|
||
- `Sunlit` (amber, sun icon) — ef = 0
|
||
- `XX% sunlit` (muted, eclipse icon) — 0 < ef < 1
|
||
- `Eclipsed` (dim, eclipse icon) — ef >= 1
|
||
|
||
Expanded pass detail shows full illumination panel: sunlit percentage, shadow status at AOS/TCA/LOS, plus entry/exit times for partial eclipses.
|
||
|
||
### 3. Code review findings (pre-existing)
|
||
|
||
The Apollo review caught a pre-existing bug in `_whats_up_pg_orrery` — the response dict was missing the `timestamp` field that the frontend TypeScript interface requires as non-optional. Fixed by computing `now_iso = datetime.now(UTC).isoformat()` and adding `"timestamp": now_iso` to every dict in the list comprehension.
|
||
|
||
### 4. One observation on eclipse entry/exit semantics
|
||
|
||
`satellite_next_eclipse_entry(tle, aos_time)` scans forward from AOS to find the *next* shadow ingress. For a pass that starts in shadow and exits to sunlight, the "next entry" is actually the *next orbit's* shadow ingress — after the pass ends. The timestamps are physically correct, but the UX label "Shadow entry" can be slightly misleading when it shows a time after LOS. Not a bug — just worth noting for Tier 2 if we want to clip entry/exit to the pass window.
|
||
|
||
---
|
||
|
||
**Files modified:**
|
||
|
||
| File | Change |
|
||
|------|--------|
|
||
| `alembic/versions/021_upgrade_pg_orrery_to_0_17_0.py` | New migration |
|
||
| `services/sky_engine.py` | Elongation + phase in planets CTE, NULL placeholders in 9 others, response dict, single-target SQL |
|
||
| `services/pass_finder.py` | Nested CTE for TLE reuse + eclipse columns |
|
||
| `schemas/target.py` | Added magnitude, solar_elongation_deg, phase_fraction |
|
||
| `schemas/passes_.py` | Added 6 eclipse fields |
|
||
| `web/src/lib/api.ts` | TS types for new fields |
|
||
| `web/src/components/sky/SkyTable.tsx` | "Near Sun" badge + phase display |
|
||
| `web/src/components/passes/PassTable.tsx` | Eclipse indicator + illumination detail |
|
||
|
||
---
|
||
|
||
**Next steps for pg-orrery:**
|
||
- [ ] Tier 2 candidates when ready: `observing_night_quality`, lunar libration, pass-window-clipped eclipse transitions
|
||
- [ ] Any perf notes on `satellite_eclipse_fraction` at scale? Our 48h ISS window (12 passes) returns in ~200ms total — seems fine
|