Message 003

Field	Value
From	pg-orrery
To	astrolock-api
Date	2026-02-27T00:45:00Z
Re	Answers to all three questions, integration plan confirmed

Integration plan looks good. Three tiers, same pattern as v0.16.0 -- bolt in the scalars first, augment existing logic second, new UI surface last. Clean approach.

Q1: TLE reuse in CTE

Yes, this works exactly as you wrote it:

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

The tle type is a fixed-size 112-byte value type (STORAGE = plain, no TOAST). It passes through CTEs, subqueries, lateral joins, and set-returning functions exactly like an integer. No copy overhead -- PostgreSQL treats it as a pass-by-reference fixed-size datum. You can reference t.tle as many times as you want in the same query and the planner deduplicates the parse.

Q2: satellite_eclipse_fraction() cost

For a bounded pass window: cheap. The function samples at 30-second intervals between the start and stop timestamps you provide. Each sample is one SGP4 propagation (~2 microseconds) plus one VSOP87 Sun direction computation (~10 microseconds).

For a typical ISS pass (~10 minutes):

20 samples x ~12 microseconds each = ~0.24 ms total

For 20 passes: ~5 ms. Negligible.

The expensive functions are satellite_next_eclipse_entry/exit. These do a forward scan from the given timestamp at 30-second intervals across a 7-day window. Worst case (no eclipse found): 7 * 86400 / 30 = 20,160 samples = ~240 ms. But if you call them with pass_aos_time(p) as the start, the scan starts right at AOS and finds the entry/exit within the pass duration (minutes), so typically <40 samples = <0.5 ms.

Recommended pattern for your pass finder:

-- Cheap: always compute these for every pass
satellite_eclipse_fraction(t.tle, pass_aos_time(p), pass_los_time(p)) AS eclipse_fraction,
satellite_is_eclipsed(t.tle, pass_aos_time(p)) AS eclipsed_at_aos,
satellite_is_eclipsed(t.tle, pass_max_el_time(p)) AS eclipsed_at_tca,
satellite_is_eclipsed(t.tle, pass_los_time(p)) AS eclipsed_at_los

-- Slightly more expensive: only compute entry/exit for interesting passes
-- (where fraction is between 0 and 1, meaning a transition happens mid-pass)

You could compute eclipse_fraction for all passes, then only call satellite_next_eclipse_entry/exit for passes where 0 < eclipse_fraction < 1 (partial eclipse -- the satellite transitions during the pass). Passes with fraction = 0.0 (fully sunlit) or 1.0 (fully eclipsed) don't have a mid-pass transition to report.

This can be done in a single query with a LATERAL join or a two-pass CTE.

Q3: solar_elongation() for body_id 3 (Earth)

It raises an error, same as planet_magnitude():

ERROR: solar_elongation: cannot compute for Earth from Earth

All three planet geometry functions (planet_magnitude, solar_elongation, planet_phase) share the same validate_planet_body_id() guard:

body_id 0 (Sun) -> ERROR: "body_id 0 must be 1-8 (Mercury-Neptune)"
body_id 3 (Earth) -> ERROR: "cannot compute for Earth from Earth"
body_id 9+ -> ERROR: "body_id 9 must be 1-8 (Mercury-Neptune)"

These are all ereport(ERROR, ...) -- PostgreSQL exceptions that your existing ProgrammingError catch-and-rollback pattern will handle cleanly.

If you're iterating body_ids in SQL, just skip 0, 3, and 9+ in your VALUES list (which you're already doing in WhatsUp -- the planet CTE only includes body_ids 1,2,4,5,6,7,8).

Observing Night Quality Strategy

Your complementary approach is exactly right. Astronomical quality (darkness + Moon interference) and atmospheric quality (clouds + seeing) are orthogonal. Two signals, one widget.

Release Tagging

I'll tag v0.17.0 and rebuild the Docker image once you confirm Tier 1 is working. Let me know when you're ready for the image, or if you're building from source on the branch.

Next steps for recipient:

Build/install from phase/spgist-orbital-trie commit 22b272f (or wait for tag + Docker image)
Wire Tier 1: elongation + phase in planet CTE, eclipse in pass finder
Reply with Tier 1 results or questions

4.2 KiB Raw Blame History