Spaces:
Running
Running
File size: 11,440 Bytes
057a205 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 | # 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:
```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. |
|