spherex-projects / DOME_CONTRACT.md
AkshithSurya's picture
Deploy SPHEREx Data Explorer (Static)
057a205 verified
|
Raw History Blame Contribute Delete
11.4 kB

SPHEREx Dome — Contract v0.5 (Phase 0)

Status: DRAFT until you approve it in chat. After approval it is frozen for the Nov 1 build; any change bumps the version and is listed in section 13. Rule: every piece (D1–D7, B1–B2, T1, P2, F1–F3) is written and tested against this file. If code and contract disagree, the contract wins until it is formally changed.


1. Promise

Start inside the sky, change what wavelength you see, pick a point, and carry that exact position into the professional workspace — then come back with the context intact.

The dome is the invitation. Professional Mode is the proof. Nothing in the dome claims more than the data behind it.

2. Scope for Nov 1

In Out (after Nov 1)
Dome, 3 full-sky layers, look/zoom, click-to-select, RA/Dec readout, simulated observer on a grass field with a horizon Real location / real time / time controls
Real SPHEREx field outline + "frames nearby" count (local archive) Tiled high-resolution HiPS dome, SPHEREx all-sky layer
Handoff to the existing Aladin / FITS / overlay / terrain views and return Evidence chain panel (P3), floating panel system (P4)
Intro modal, hamburger menu (as time allows) AI assistant (A1, A2) — no AI anywhere in the dome

3. Sky and projection (T1, D4, F2 depend on this)

  • Frame: ICRS (J2000 equatorial). Galactic (l, b) is shown in the readout only.
  • Observer model (v0.5): a simulated observer on a flat grass field. An observer is { lat, lst } (latitude and local sidereal time, degrees). It is fixed: default latitude 30° S, and a fixed moment chosen so the SPHEREx field starts 22° above the horizon. It is not the viewer’s location and not the current time, and the UI says so (section 8). The camera is alt-az: altitude = pitch, azimuth = −yaw (N=0, E=90). The ground is opaque and covers everything below the horizon; the SPHEREx field is only ever shown above it. A clicked point below the horizon is “ground” and has no sky coordinates. World frame: +X east, +Y up, −Z north. The sky group is rotated by observerMatrix(obs) (dome-coords.js), verified in tests/dome_coords_test.js against textbook hour-angle formulas (650 points, 5 observers). Landscape (dome-landscape.js): procedural dark grass, distance fog, horizon glow, compass points; no image files.
  • Texture: equirectangular, 2:1, default 4096 × 2048 (0.088°/px).
ra_deg  = 360 * (1 - (u + 0.5) / width)      RA increases right-to-left (east is left)
dec_deg =  90 - 180 * (v + 0.5) / height     Dec increases bottom-to-top (north is up)
u = (1 - ra/360) * width - 0.5               v = (90 - dec)/180 * height - 0.5
  • World mapping (3D), defined and tested by D4/F2 (dome-coords.js, tests/dome_coords_test.js):
direction = ( cos(dec)*cos(ra),  sin(dec),  -cos(dec)*sin(ra) )     +Y = celestial north pole
camera:   RA = yaw + 90 degrees,   Dec = pitch                      (rotation order YXZ, no roll)

Looking outward with north up, east (larger RA) is on the left. The F2 suite checks this against the Three.js r128 sphere vertex formula and real rotation matrices, not against the maths above. The landmark table below still decides if anything ever disagrees.

Landmark anchors at 4096 × 2048 (F2 and the Tuesday visual check use these):

Landmark RA° Dec° u v
SPHEREx field centre 127.571 −39.214 2644.0 1469.7
M31 (Andromeda) 10.6847 +41.2692 3973.9 553.9
M42 (Orion Nebula) 83.8221 −5.3911 3141.8 1084.8
Sgr A* (Galactic Centre) 266.4168 −29.0078 1064.3 1353.5
Polaris 37.9546 +89.2641 3663.7 7.9

Pass criteria: dome mapping round-trips to < 0.01° for every landmark; the bright Galactic Centre bulge appears at the Sgr A* pixel; Orion's belt region appears near M42. Note: the field centre is at Galactic latitude b ≈ 0.0° — the opening view sits on the Milky Way plane.

4. Layers

Layer ids equal the existing SKY_SURVEYS keys in s.py, so the dome and Aladin share survey ids.

id Stop label Survey (HiPS id) Approx. wavelength
dss2-color Optical DSS2 color (CDS/P/DSS2/color) 0.4–0.9 µm
2mass-color Near-infrared 2MASS color (CDS/P/2MASS/color) 1.2–2.2 µm
allwise-color Mid-infrared AllWISE color (CDS/P/allWISE/color) 3.4–22 µm
  • Wavelength figures are approximate and say so in the UI tooltip.
  • SPHEREx itself covers 0.75–5 µm; the strip may mark that span across the Near-IR/Mid-IR stops.
  • Switching layer never moves the camera or the selected target.
  • Every layer shows its survey name and credit text (from manifest.json).

5. Start state and camera

Item Value Why
Start centre RA 127.571°, Dec −39.214° (alt 22°, az ≈ 124° SE) Centre of the 434 local SPHEREx frames
Start FOV 75° Shows the horizon and the grass at the bottom of the view
FOV limits 35° – 100° 4096 px texture gets soft below ~35°
Pitch limits −35° … +89° (altitude) Look down at the grass, up to near the zenith; ±85° if no observer is set
Reset returns to start centre/FOV Always available

Known limit (will be stated in the demo): at 0.088°/px the SPHEREx field is only ~100 px across. The dome is for orientation; detail lives in Professional Mode.

6. Interaction and selection

  • Drag looks around. A press that moves < 4 px is a click; ≥ 4 px is a drag. Never both.
  • Click → ray → RA/Dec → marker + readout chip showing: decimal RA/Dec, sexagesimal RA/Dec, Galactic l/b, current layer, and the button "Investigate this region".
  • Selection radius for the observation lookup: 0.25°.
  • Count text: "N local SPHEREx frames nearby" (never "covering"). Reason: the server matches on frame centres within radius + 2.5°, not on exact footprint polygons. Exact coverage is a later task.
  • Zero results reads "No local SPHEREx frames near this point" and the button stays enabled (Professional Mode can still search IRSA).
  • The local-field outline is the real union of footprints.json polygons, drawn thin and dim.

7. Handoff state (B1 owns it; P2 consumes it)

Client-side object, serialisable to JSON:

{
  "mode": "dome",
  "targetName": null,
  "ra": 127.571,
  "dec": -39.214,
  "survey": "2mass-color",
  "wavelengthRange": [1.2, 2.2],
  "searchRadius": 0.25,
  "selectedBand": null,
  "camera": { "ra": 127.571, "dec": -39.214, "fov": 70 },
  "selectedObservation": null
}
Field Meaning Server DomeSession field
mode "dome" or "professional" client-only
targetName, ra, dec selected target, ICRS degrees targetName, ra, dec
survey layer id from section 4 currentSurvey
wavelengthRange micrometres wavelengthRange
searchRadius degrees searchRadius
selectedBand SPHEREx band, if chosen selectedBand
camera look direction and FOV client-only
selectedObservation opaque id (obs_spx_...) client-only

Rules: layer switching changes survey and wavelengthRange only. Going to Professional Mode and back must restore camera, the marker and the selection exactly.

8. Honesty labels (non-negotiable)

  1. Dome sky = real survey imagery, resampled to a panorama. It is not SPHEREx data.
  2. SPHEREx pixels appear only in Professional Mode (FITS / mosaics).
  3. The field outline and frame count are real, from the local archive.
  4. No AI output exists in the dome. Later AI output must show confidence, caveats, evidence and model version.
  5. Every layer displays survey name + credit. Missing credit text is a build warning, not a silent blank.
  6. The observer is simulated: the HUD says “Simulated sky: latitude 30° S, fixed moment”. Never imply it is the viewer’s location or the live sky.

9. Failure and fallback

Failure Behaviour
No WebGL Message "3D view unavailable on this device" + button into Professional Mode
Texture fails to load Previous layer stays visible; status chip "Layer unavailable"; camera and target untouched
/api/observations/search fails or slow Marker and RA/Dec still appear; count shows "Lookup unavailable"; handoff still works
/api/session unreachable Dome runs on client state only (nothing in the dome depends on it)
Texture orientation check inconclusive at build Build warns; F2 landmark test is the gate — do not ship until it passes

10. Style rules (F1 owns them)

  • Use tokens.css only. Ground #061522, accent #66b9ef, orange #d94d35 for primary actions only, cream #d9d5c5 for brand marks. No new palette, no new font.
  • Quiet at rest: edge controls low-opacity until pointer proximity, focus, or tap; HUD fades when idle.
  • Instrument feel: thin 1 px lines, small mono readouts (--font-mono), no emoji, no decorative motion.
  • Keyboard reachable, visible focus ring, honours prefers-reduced-motion.
  • No new framework. Plain JS files beside index.html; Three.js stays at r128 (already loaded). Never use APIs newer than r128 (e.g. CapsuleGeometry, outputColorSpace).

11. File plan

index.html            (touched only at marked insertion points)
dome.js               D1 scene core          dome-look.js   D2 look controller
dome-layers.js        D3 sky layers + crossfade
dome-landscape.js     D8 grass field, horizon, fog, compass
dome-coords.js        D4 coordinate engine   dome.css       F1 style (not yet written)
app-state.js          B1 state/router (not yet written)
sky_layers/           *.jpg + manifest.json
tools/build_sky_textures.py
tests/dome_coords_test.js  tests/dome_coords_test.html
dome_test.html        manual test page
DOME_CONTRACT.md

12. Definition of done (Nov 1 acceptance path)

On the deployed site, a stranger can: (1) look around; (2) switch wavelength without the view moving; (3) click a point and read its coordinates; (4) see the local-frame count near the field; (5) press "Investigate this region"; (6) land in the existing views with the same target and survey; (7) return to the dome and find the camera, marker and selection as left. All landmark tests pass.

13. Decisions to confirm, and change log

Confirm before Day 2:

  1. Layer set and stop labels (section 4): Optical / Near-infrared / Mid-infrared.
  2. Texture size: 4096 default; allow an optional 8192 build for desktop later.
  3. Opening view on the field centre (on the Galactic plane), FOV 70°.
Version Change
0.1 Initial draft
0.2 Section 3: opaque ground removed; observer platform + Dec=0 “celestial equator” ring instead (found while building D1)
0.3 Section 3: world mapping defined and test-verified (yaw+90 = RA, pitch = Dec). Section 11: added dome-look.js, tests.
0.4 Section 11: added dome-layers.js (D3). Layers are read from manifest.json; layer set may now include mellinger-color.

| 0.5 | Reverses v0.2/v0.3: observer model added so the viewer stands on a grass field (Stellarium-style). Fixed simulated observer (lat 30° S, fixed moment). Pitch −35…+89°. Start FOV 75°. New piece D8 (dome-landscape.js). 42 coordinate tests. |