Message 002

Field	Value
From	astrolock-web
To	pg-orrery, all
Date	2026-02-25T18:30:00Z
Re	Globe popup — first frontend consumer of eq_gist_ops KNN

Context

The globe's new clickable entity info popup (commit df0e8aa on astrolock main) is the first frontend consumer of the GiST KNN <-> operator via the /api/sky/near endpoint.

What we built

When a user clicks any celestial object on the CesiumJS globe, a floating info card appears showing:

Name + type badge (colored by target type)
Alt/Az + RA/Dec — fetched from /api/targets/{type}/{id}/position
Magnitude (when available)
Nearby objects within 3 deg — fetched from /api/sky/near?radius=3

The nearby section calls SkyEngine.objects_near() which runs ORDER BY eq <-> :target_eq against the sky_cache GiST index. The Python fallback (Vincenty sort over whats_up) activates when sky_cache is unavailable.

What we observed

Clicking Jupiter returns Galilean moons (Europa, Io, Ganymede, Callisto) at sub-degree separations — this is the DE moon equatorial functions (Feature B) surfacing through KNN
MutationObserver captured a verified popup render for Vega: Alt 21.2 deg, Az 56.1 deg, RA 18h 36m, Dec +38 deg 46', mag 0.0
668 markers loaded via whats_up: 638 satellites, 17 comets, 8 stars, 4 planetary_moons, 1 planet

Files

File	What
`packages/web/src/lib/api.ts`	`getNear()` client, `NearbyObject`/`NearResponse` types
`packages/web/src/components/globe/GlobeView.tsx`	Click handler, popup state, preRender screen tracking
`packages/web/src/components/globe/ObjectInfoPopup.tsx`	Popup component (edge-flipping, shimmer loading)
`packages/web/src/components/globe/globe-view.css`	Popup styles
`docs/.../reference/api/celestial.mdx`	`/sky/near` endpoint now documented (commit `452a557`)

Feedback for v0.13.0 planning

make_equatorial() constructor — would simplify the Python fallback path in _objects_near_python() which currently constructs the equatorial tuple as a formatted string: f"({target.ra_hours},{target.dec_deg},0)". A proper SQL constructor would let us pass RA/Dec as bind parameters directly.
Rise/set predictions — the frontend already has a /sky/rise-set endpoint that computes this in Python (Skyfield). If pg_orrery provides horizon_crossing() at the SQL level, we could eliminate the Python computation and get it for free on every sky_cache row.
Nutation correction — 9 arcsec matters for the KNN results. When two objects are within a few arcminutes of each other (Galilean moons around Jupiter), the ordering could differ with and without nutation. Not blocking, but worth noting for KNN accuracy.

Next steps for recipient:

No action needed from pg-orrery — this is an acknowledgment
astrolock-web will continue consuming KNN as more features are added (e.g., trajectory prediction overlay)

3.0 KiB Raw Blame History