Spaces:
Running
Running
|
Download README_DOME.md from AkshithSurya/spherex-projects: direct link, hf CLI and curl.
- Browser
- Download file 8.8 kB
-
https://huggingface.co/spaces/AkshithSurya/spherex-projects/resolve/main/README_DOME.md
- Command line
-
hf download hf://spaces/AkshithSurya/spherex-projects/README_DOME.md
-
curl -L -o README_DOME.md https://huggingface.co/spaces/AkshithSurya/spherex-projects/resolve/main/README_DOME.md
8.8 kB
| # SPHEREx Sky Dome | |
| A dome-first front door for the SPHEREx Data Explorer. You start **standing on a grass field under a simulated sky**, | |
| look around, switch between optical, near-infrared and mid-infrared views of the sky, click a point, see the SPHEREx | |
| frames nearby, and press **Investigate this region** to open that exact position in the existing Explorer | |
| (sky map, search, FITS tools). A **Return to dome** button brings you back with the view and selection intact. | |
| Plain JavaScript, Three.js r128 (already loaded by `index.html`), no build step, no new Python packages. | |
| ## Install (3 commands) | |
| Unzip this package **into the project folder** (the one containing `s.py` and `index.html`), then: | |
| ```bash | |
| python3 tools/install_dome.py --test # checks files, patches s.py + index.html, runs the tests (--test needs Node) | |
| python3 s.py # start the server as usual | |
| # open http://localhost:8000/ # the dome opens first | |
| ``` | |
| `?dome=0` on the address opens the normal app with no dome. `python3 tools/install_dome.py --uninstall` removes the | |
| dome block from `index.html`. Backups: `s.py.bak`, `index.html.bak`. | |
| What the installer changes (nothing else is touched): | |
| | File | Change | | |
| |---|---| | |
| | `s.py` | adds an **allowlisted** static route: `dome*.js`, `dome*.css`, `app-state.js`, `sky_layers/*.jpg|json`. Without it the server returns 404 for every dome file (it only serves a fixed whitelist). | | |
| | `index.html` | adds one block of `<script>` tags before `</body>` (12 lines, no removals). | | |
| The server's local-only guard (`_require_local_request`) is unchanged: **run it on your own machine.** Putting it on a | |
| public host needs a deliberate, reviewed change there (see Limits). | |
| ## What it does | |
| - **Look:** drag, scroll/pinch zoom, arrow keys, `+`/`-`, `R` reset. Look down to see grass, up toward the zenith. | |
| - **Sky layers:** optical (DSS2), near-infrared (2MASS), mid-infrared (AllWISE), crossfade without moving the view. | |
| Credit text and approximate wavelength are shown for each. Optional smoother optical layer: Mellinger (see Limits). | |
| - **Select:** click the sky for a marker, RA/Dec (sexagesimal and decimal), altitude/azimuth, Galactic l/b and | |
| "N local SPHEREx frames nearby". Click the ground: no coordinates. `Esc` clears. | |
| - **SPHEREx field:** the real footprints (434 frames, dim) and their outline, from your `footprints.json`. | |
| - **Go to object:** type a name (M42, Sirius, Orion...). Well-known names work offline; others use the existing resolver. | |
| Objects below the horizon are explained, not hidden. | |
| - **Time:** slider +/-12 h and Play (1 simulated hour per second). Brightness slider (display only, data untouched). | |
| - **Menu:** toggle ground, compass, field outline, equator ring; Open Professional Mode; Help. | |
| - **Intro + tips:** first-visit introduction, then tips that tick off as you try each thing. | |
| - **Handoff:** Investigate calls the existing `showSkyMap()`, `applySky(key)`, `setSearchCenter(ra, dec, {flyTo, label})` | |
| and `runSearch()`; the search radius field is set from the dome. Missing functions are logged, never fatal. | |
| ## Files | |
| | File | Role | | |
| |---|---| | |
| | `dome-coords.js` | RA/Dec <-> directions, observer (alt-az) maths, galactic, formatting. Pure functions. | | |
| | `dome.js` | 3D scene: sky sphere, crossfade overlay, observer tilt, brightness, pause when hidden. | | |
| | `dome-look.js` | Mouse/touch/keyboard looking, click-vs-drag, limits, exact camera save/restore. | | |
| | `dome-layers.js` | Reads `sky_layers/manifest.json`, loads textures, crossfades, handles failures. | | |
| | `dome-landscape.js` | Procedural grass, horizon glow, fog, compass points (no image files). | | |
| | `app-state.js` | The handoff state store (target, layer, camera, selection) with validation. | | |
| | `dome-select.js` | Click -> selection, marker, observation lookup, field outline. | | |
| | `dome-hud.js` | All on-screen controls, intro modal, tips. Minimal CSS in one block, easy to restyle. | | |
| | `dome-app.js` | Wires everything, mounts the dome, performs the handoff and the return. | | |
| | `sky_layers/` | `manifest.json`, the sky `.jpg` panoramas, `field_polys.json`. | | |
| | `tools/` | `install_dome.py`, `patch_server.py`, `patch_index.py`, `build_sky_textures.py`, `build_field_outline.py`. | | |
| | `tests/` | 10 automated test files + `run_all.js`; `dome_coords_test.html` in a browser. | | |
| | `dome_test.html` | Stand-alone test page (needs `python3 -m http.server`); names any missing file on screen. | | |
| | `DOME_CONTRACT.md` | The design contract (what the dome may and may not claim). | | |
| ## Testing | |
| **Automated (no browser, no network):** `node tests/run_all.js` -> 307 checks across coordinates, scene, look controls, | |
| layers, landscape, state, selection, HUD and the app glue. The 3D scene is tested against recording fakes, and | |
| several tests were validated by deliberately breaking the code to see them fail. | |
| **Server, verified against the real `s.py`:** the six dome URLs return 200 with correct types; 15 traversal and | |
| non-allowlisted URLs return 404; a wrong Host header still returns 403; the lookup request returns real counts | |
| (field centre 434, field edge 147, M42 0) and rejects a radius above 5. | |
| **Browser checklist (a human must do this; it has not been done by the author of this code):** | |
| 1. Open `http://localhost:8000/`. The dome opens: dark grass at the bottom, glowing horizon, the sky above. | |
| 2. The readout says **alt 22.0** at the start. A thin outline with many small boxes sits around the view centre. | |
| 3. Drag/zoom/keys work; N/E/S/W compass points are readable; facing south, E is on your left. | |
| 4. Click each layer button: smooth fade, readout does not change. | |
| 5. Click a bright star: ring appears, coordinates and "N local SPHEREx frames nearby" show. Click the grass: a message. | |
| 6. **Investigate this region** -> the Explorer opens centred on that point, same survey, radius 0.25, search runs. | |
| 7. **Return to dome** -> same camera, same ring, same layer. | |
| 8. Go to object `M42`; try the time slider; try `?dome=0`. | |
| 9. Stop the server's API (or rename a `.jpg`) and confirm friendly messages, not a blank screen. | |
| 10. Phone: drag, pinch, tap. | |
| ## Limits (be honest about these when demoing) | |
| - **The sky is survey imagery, not SPHEREx data.** SPHEREx pixels appear only in Professional Mode. | |
| - **The observer is simulated:** latitude 30 degrees S and a fixed moment chosen so the SPHEREx field starts 22 degrees up. | |
| It is not the viewer's location or the live sky (the HUD says so). Change `lat` / `startAlt` in `dome-app.js` DEFAULTS. | |
| - "N local SPHEREx frames nearby" means frame **centres** within the search radius plus 2.5 degrees (how the server | |
| matches), not exact coverage. | |
| - Texture resolution is 4096x2048 (0.088 deg/pixel): stars are soft when zoomed. The 9-degree SPHEREx field is ~100 px wide. | |
| - **Layer quality:** DSS2 shows a checkerboard of mismatched patches; AllWISE is blocky and dark. 2MASS is clean. | |
| `mellinger-color` (smooth optical) can be built with `python3 tools/build_sky_textures.py --only mellinger-color`, but | |
| that image is copyright Axel Mellinger: check its terms before public use. The Explorer calls it `mellinger`. | |
| - **Not for public hosting as is:** the server only answers requests whose Host is localhost. | |
| - `requirements.txt` in the project is wrong (says "standard library only"; `s.py` imports numpy, astropy, scipy). | |
| Use `requirements_suggested.txt`. | |
| - Never viewed in a real browser by the author: the maths, state, networking and wiring are tested; the **look** (colours, | |
| grass, haze, HUD layout) is not. Expect to tune colours and spacing. Styling is intentionally minimal. | |
| ## Troubleshooting | |
| - **Flat blue-grey screen, no buttons:** a script failed to load. Open `dome_test.html`: it prints "Missing file: ..." or | |
| the script error. In the app, open the browser console (F12) and look for 404s. Hard-refresh with Ctrl+Shift+R. | |
| - **404 for `/dome.js` in the app:** the server patch was not applied or the server was not restarted. | |
| - **No sky photo, only dark:** `sky_layers/manifest.json` or the `.jpg` files are missing (see the installer message). | |
| - **"Lookup unavailable":** the `/api/observations/search` call failed; the marker and coordinates still work. | |
| - **Dome covers the app and you want it gone:** add `?dome=0`, or run `--uninstall`. | |
| - **Rebuild the sky pictures:** `pip install numpy pillow` then `python3 tools/build_sky_textures.py` (needs internet; | |
| it checks image orientation against the Galactic plane and fixes a mirrored image automatically). | |
| ## Design contract | |
| `DOME_CONTRACT.md` is the single source of truth for what the dome promises, its coordinate conventions | |
| (RA runs right-to-left in the panorama, east is left, world mapping verified by tests), the handoff state, honesty | |
| labels, fallbacks and the known blockers outside the dome code. | |