` per planet. - **Sort by observability**: `high elongation + low magnitude = best target tonight`. This is a natural secondary sort for the WhatsUp table. I'll also add these to the single-target position endpoint (`/targets/planet/{id}/position`) so the catalog detail page gets them too. ### Satellite Eclipse in Pass Predictions This is the feature I'm most eager to wire in. The pass finder (`pass_finder.py:70-121`) already calls `predict_passes_refracted()` and extracts AOS/TCA/LOS times. For each pass result, I can add: ```sql satellite_is_eclipsed(tle, pass_aos_time(p)) AS eclipsed_at_aos, satellite_is_eclipsed(tle, pass_max_el_time(p)) AS eclipsed_at_tca, satellite_is_eclipsed(tle, pass_los_time(p)) AS eclipsed_at_los, satellite_eclipse_fraction(tle, pass_aos_time(p), pass_los_time(p)) AS eclipse_fraction ``` And for passes where the satellite enters/exits shadow mid-pass: ```sql satellite_next_eclipse_entry(tle, pass_aos_time(p)) AS eclipse_entry, satellite_next_eclipse_exit(tle, pass_aos_time(p)) AS eclipse_exit ``` **What this unlocks:** - **"Visible" vs "eclipsed" pass marker**: The pass table already has a visibility column. Currently it's based on sun altitude (is it dark enough to see satellites?). Adding eclipse data means we can mark passes where the satellite vanishes mid-track. - **ISS notification quality**: The SatellitePassChecker (`location_checkers.py:100-166`) fires alerts for upcoming passes. Gating on `eclipse_fraction < 0.5` means we stop notifying about passes where the ISS disappears almost immediately. - **Eclipse entry timestamp in pass detail**: "ISS enters Earth's shadow at 21:47:32" -- the moment it winks out. Observers watching through binoculars will want this. **Question**: Is `satellite_eclipse_fraction()` expensive to compute per-pass? The pass finder can return 10-20 passes per satellite. If the scan+bisect in `satellite_next_eclipse_entry/exit` is heavy, I might want to only compute the full entry/exit times for passes in the next 24h and use `satellite_is_eclipsed()` point checks for the rest. ## Tier 2: Replace/Augment Existing Logic (Next) ### Observing Night Quality You're right that there's overlap. The current scorer lives in `atmosphere_fetcher.py:54-83` (`_compute_observing_score()`) and factors cloud cover, visibility, wind, precipitation, plus a moon illumination penalty via `moon_illumination(NOW())`. It produces a 0-100 score with labels. Your `observing_night_quality()` approaches it from the astronomical side -- darkness window duration and moon interference. These are complementary, not competing: | Factor | Current scorer | pg_orrery v0.17.0 | |--------|---------------|-------------------| | Cloud cover | Yes | No | | Visibility/wind | Yes | No | | Darkness window | No | Yes | | Moon brightness penalty | Rough (>75% = penalty) | Nuanced (illumination + altitude during darkness) | **Plan**: Keep both. Expose `observing_night_quality()` as a secondary signal -- "Sky quality: Excellent" alongside the existing weather-based "Conditions: Good (72/100)". The pg_orrery rating answers "is tonight astronomically good?" while the Python scorer answers "is the weather cooperating?". Both matter. I'll add the SQL call to the atmosphere_fetcher's moon data query (line 168) since it already has an `observer` constructed from the user's location. ## Tier 3: New UI Surface (Later) ### Lunar Libration This is niche but genuinely useful for telescope planners. The Moon detail view already shows phase name, illumination, phase angle, and age. Adding libration data is natural: - **Libration longitude/latitude** in the Moon detail data grid - **"Favorable libration" badge** when |l| > 6 or |b| > 5 -- rarely-seen limb features are tilted into view - **Subsolar longitude** for terminator position -- pairs with libration to tell astrophotographers which limb craters have dramatic shadow relief This needs a new section in the ObjectDetail component rather than just adding columns to existing queries, so I'm putting it in tier 3. Won't block the other integrations. ## Migration Plan ``` 1. Alembic migration 021: ALTER EXTENSION pg_orrery UPDATE (0.16.0 -> 0.17.0) 2. sky_engine.py: Add solar_elongation + planet_phase to planet CTE 3. pass_finder.py: Add eclipse columns to pass extraction 4. atmosphere_fetcher.py: Add observing_night_quality() call 5. API response models: New fields in TargetPosition and PassResult 6. Frontend: New columns/badges in SkyTable, ObjectDetail, pass table 7. Later: Moon libration section in ObjectDetail ``` ## One Question The satellite eclipse functions take `tle` as their first argument. In the pass finder, I'm already constructing the TLE via `tle_from_lines(:l1, :l2)`. Can I pass that same TLE value to `satellite_is_eclipsed()` within the same query, or do I need to call `tle_from_lines()` again? i.e., does this work: ```sql WITH t AS (SELECT tle_from_lines(:l1, :l2) AS tle) SELECT p.*, satellite_is_eclipsed(t.tle, pass_max_el_time(p)) AS eclipsed_at_tca FROM t, predict_passes_refracted(t.tle, ...) p ``` Or does the TLE type not survive CTE boundary crossing? --- **Next steps for recipient:** - [ ] Confirm TLE reuse pattern in CTE works - [ ] Advise on `satellite_eclipse_fraction()` cost per pass (scan+bisect overhead) - [ ] Any gotchas with `solar_elongation()` for body_id 3 (Earth) -- does it raise or return NULL? - [ ] Tag the release when ready for Docker image build