See when the Sun and Earth stay above the horizon at any landing site near the Moon's south pole.
Moonset is a lunar landing-site navigator built for the NASA Space Apps Challenge 2026 ("Lunar Landing Site Navigator"). Pick a place on the Moon and it tells you, minute by minute, when the Sun rises and sets behind the real mountains there, when Earth (and so direct radio contact) is in view, how long the nights last, how much solar energy a lander gets, and how steep the ground is. It then helps a mission team pick a site, pick a date, compare options and re-plan fast when something changes.
Every number is computed live in the browser from NASA data: LOLA terrain from the Lunar Reconnaissance Orbiter and Sun/Earth positions from JPL's DE440 ephemeris (SPICE). Nothing is pre-baked or typed in.
Team: Muhammad Asjed and Zainab.
- Quick start
- What it does
- How it works
- Repository layout
- Running, testing, formatting
- Hosting
- Debugging: where to look when something breaks
- Accuracy and validation
- Design system
- Data sources and credits
- Further docs
You need any static web server. Nothing to install, no build step.
git clone https://github.com/MIGHTYASJED/moonset.git
cd moonset
python3 -m http.server 8080 --directory web # or: npm startOpen http://localhost:8080. Use Chrome, Edge, Safari 16.4+ or Firefox 113+ (the app needs WebGL and
DecompressionStream).
Opening
web/index.htmlstraight from disk (file://) does not work: browsers block the data downloads. Always use a server.
The app has a scrolling home page and three working views (tabs in the top bar), plus overlays.
| Part | What the user gets |
|---|---|
| Home | Cinematic Sun–Earth–Moon hero and "Go to the south pole", then a scroll-driven "lunar day at the south pole" drawn from the engine: Malapert's real LOLA skyline with the real Sun and Earth over one lunar day, centred on a real night behind the ridge (date and time shown; heights exaggerated and labelled). Below: the NASA star map, slowly turning Moon and Earth, an animated ray-trace of the skyline over the real south-pole relief, and the accuracy numbers. |
| Map | South-pole map (NASA terrain, live shadows at the chosen moment) and a whole-Moon map. 42 curated sites (Artemis candidate regions, Apollo, Luna, CLPS, Chang'e, Chandrayaan…). Click anywhere to analyse any point. Heat layers for sunlight / Earth view / both, "top spots", plain-language "find spots" search. |
| Place panel | Opens on the right (a sheet on phones). Headline verdict, countdowns (sunset, sunrise, Earthset, Earthrise), Sunlight %, Earth in view %, longest night, longest radio gap, energy per m², next 12 months, Terrain check (two NASA terrain models side by side), landing-area slope, best landing dates, landing risk, plan/alternates. |
| Site | Eye-level sky view from the selected place: the real skyline, true-size Sun and Earth, their paths, countdowns, and a Full screen mode (keys F, S, E, B, H, Esc). |
| Plan | Six-step mission planner: pick candidates, best landing dates, compare side by side, lock the plan (checks: Sun up at touchdown, battery, radio silence, energy vs load, landing-area slope), "something changed" (launch slip / site lost → ranked alternates in about half a second), export (text, CSV, JSON, calendar). |
| Stand here | Inside NASA's south-pole terrain: a first-person walk on 5 m terrain with the real Sun, Earth and shadows. Elsewhere: the full-screen sky view for that place. |
| Ask | Natural-language assistant. Offline mode works with no internet or key ("Which site gets the most sunlight?", "When is sunset at Haworth?", "Malapert is lost, where else within 50 km?"). Optional Gemini mode with the user's own Google AI Studio key. Every number comes from the engine. |
| Tour | On the first visit a small card offers "Take the tour" or "Skip". The tour spotlights each part of the interface (map, search, layers, place panel, Moment, Study window, timeline, Site, Plan, Ask) with one short explanation each. Replay it from the "?" button in the top bar or from Method & accuracy. |
| Simple / Expert | Simple: plain words, finger-widths, rounded times. Expert: UTC, degrees, uncertainty ranges, extra inputs (battery Wh, loads, panel area). |
| Light / Dark | Both themes everywhere; maps and skies stay dark "windows". |
The two time controls matter and appear everywhere:
- Study window (bottom left): the span every percentage and "longest" number covers, e.g. "14 days from today".
- Moment (scrubber, date chip in the top bar): the instant the sky, shadows and countdowns show. Play runs time forward.
| Layer | Choice | Why |
|---|---|---|
| App | Plain JavaScript (ES2020), HTML, CSS, no framework, no bundler | The heavy part is numerical (terrain ray-tracing, ephemeris) and canvas/WebGL drawing, where a framework adds nothing. No build step means the repo runs anywhere, deploys as static files and is easy to read. |
| 3D | three.js r128, vendored in web/vendor/ |
Globe, hero, Stand here and Walk. Vendored so the app works offline and never breaks on a CDN change. |
| Parallel work | Web Workers (web/js/engine/jobs.js) |
Long analyses (heat maps, 12-month scans) run off the main thread. |
| Data pipeline | Python 3 (numpy, rasterio, spiceypy, Pillow) in pipeline/ |
Turns raw NASA GeoTIFFs and SPICE kernels into the compact files the browser loads. |
| Tests | Node (engine numbers) + Python Playwright (whole app in headless Chrome) | Engine tests run in under a second in CI; the end-to-end suite drives the real UI. |
| Hosting | Any static host (GitHub Pages workflow included) | No server code at all. |
NASA raw data browser
┌──────────────────────────────┐ ┌──────────────────────────────────────────────────────┐
│ LOLA polar DEMs (80/240 m) │ │ engine/ core.js terrain ray-tracing, ephemeris │
│ LOLA global map (16 px/deg) │ py │ engine.js sites, events, window stats, │
│ SFS 5 m tiles + orthophotos │ ──► │ terrain models, slope │
│ SPICE kernels (DE440) │ │ jobs.js Web Workers for long scans │
└──────────────────────────────┘ │ terrain.js walk-mode tiles │
pipeline/*.py │ app/ store.js one shared state + formatting │
│ │ app.js shell: bar, search, time dock │
▼ │ views/ home, world (Map), globe, site, board, │
web/data/*.bin, *.json, *.jpg │ halo, stand, walk │
│ features/ panel (place panel), tools (Plan, risk, │
│ method), ask (assistant) │
└──────────────────────────────────────────────────────┘
One rule holds the app together: views never compute physics. They ask ES.engine (or ES.jobs)
and format the answer with ES.fmt. That is why the Map panel, Site view, Plan and Ask always show the
same number for the same question.
- Skyline. For a point, the engine ray-traces NASA's terrain in 720 directions out to 150 km, with lunar curvature, to get the height of the horizon in every direction.
- Two terrain models. Calibrated (default): ignores terrain within 2 km of the point, which best matches six published sunlight studies. 80 m: keeps every hill within 8 km from NASA's 80 m map, including the slope the point sits on. The Terrain check shows both and flags a spot as terrain-sensitive when they differ by 10 points or more.
- Sun and Earth. A 2-hourly table from JPL's DE440 ephemeris (2019-12 to 2036-04), interpolated.
- Rules. The Sun is up when its centre is above the skyline (plus an optional margin). Earth is in view only when its whole disc is at least 2° above the skyline (a real radio margin).
- Events. Sunrise, sunset, Earthrise and Earthset are found to the minute. Nights that start before or run past the Study window are followed to their true ends (shown with "≥" if still open after 35 days).
- One source of truth.
ES.engine.windowStats(site, jd0, days)produces every percentage and every "longest night / gap" in the app.
More detail: docs/ARCHITECTURE.md.
moonset/
├── README.md this file
├── CLAUDE.md working guide for AI coding assistants (rules, map of the code)
├── LICENSE MIT
├── package.json npm scripts (start, test, test:e2e, format)
├── .github/workflows/ci.yml engine tests on every push + GitHub Pages deploy from main
├── docs/
│ ├── ARCHITECTURE.md modules, state, data flow, how to add things
│ ├── DATA.md every data file: source, format, size, how it was made
│ ├── VALIDATION.md accuracy checks and how to reproduce them
│ ├── DESIGN.md visual design system and UX rules
│ └── TROUBLESHOOTING.md symptom → cause → fix
├── web/ THE APP (serve this folder)
│ ├── index.html page shell; loads scripts in dependency order
│ ├── css/app.css design tokens (light/dark) + shell styles
│ ├── js/
│ │ ├── engine/ core.js, engine.js, jobs.js, terrain.js (physics + data loading)
│ │ ├── app/ store.js (state, formatting), app.js (shell)
│ │ ├── views/ home, world (Map), globe, site, board, halo, stand, walk
│ │ └── features/ panel (place panel), tools (Plan + modals), ask (assistant)
│ ├── data/ NASA-derived data (≈79 MB) + sites.json + validation.json
│ └── vendor/ three.js r128 + OrbitControls
├── pipeline/ Python scripts that build web/data from raw NASA files
└── tests/
├── engine/ Node tests of the engine against published numbers
└── e2e/ Playwright suite that drives the whole app in Chrome
| Task | Command |
|---|---|
| Run locally | npm start (http://localhost:8080) or python3 -m http.server 8080 --directory web |
| Engine tests (fast, CI) | npm test or node tests/engine/engine_test.js |
| Whole-app tests | pip install playwright && python -m playwright install chromium, then npm run test:e2e (about 5 minutes; screenshots in tests/e2e/shots/) |
| Re-run the published-number check | node tests/engine/val.js |
| Re-run the held-out cross-validation | node tests/engine/cv_near.js (writes web/data/validation.json) |
| Rebuild the data | see pipeline/README.md |
| Format code | npm run format (Prettier, settings in .prettierrc.json) |
tests/e2e/run_all.py uses Google Chrome at /usr/bin/google-chrome; on other systems edit the
executable_path near the top or install Chrome there. Under software rendering it reports a few
performance warnings (perf.*, low fps); those are expected without a GPU.
The app is static files only: host the web/ folder anywhere.
- Push the repo to GitHub (see the large-file note below).
- Settings → Pages → Source: GitHub Actions.
- Every push to
mainruns the engine tests, then publishesweb/(workflow:.github/workflows/ci.yml).
- Netlify / Vercel / Cloudflare Pages: publish directory
web, no build command. - Any server (nginx, Apache, S3): copy
web/and serve it. Serve.binasapplication/octet-stream. Turn off on-the-fly compression for.binfiles: they are already gzip.
web/data/ is about 79 MB in 70 files; the largest is dem_global.bin (15.9 MB), under GitHub's 100 MB
file limit, so a normal git push works. If you prefer Git LFS, run git lfs track "web/data/*.bin"
before the first commit (the CI checkout already has lfs: true).
Open the browser console first. Modules log errors with a prefix in square brackets, e.g. [ES],
[world], [panel], [walk]. The app also exposes everything on window.ES for live inspection.
| Symptom | Look at |
|---|---|
| Stuck on the loader / blank page | Console errors; Network tab for failed data/*.bin. Are you on file://? Use a server. web/js/engine/engine.js → loadDEM. |
| Numbers look wrong for a site | ES.engine.windowStats(ES.engine.site(lat, lon), jd0, days) in the console; compare with the panel. Engine: web/js/engine/engine.js, physics: core.js. Run npm test. |
| Map is black or blank | web/js/views/world.js (drawNow, blit). Check ES.views.world._debug(). |
| Sky view wrong / empty | web/js/views/site.js (draw, compute). |
| Walk doesn't open | web/js/views/walk.js (open, canWalk); tiles from web/js/engine/terrain.js + data/walk.json. Outside south-pole terrain, Stand here opens the sky view on purpose. |
| Plan / alternates wrong | web/js/features/tools.js: checks, failWhy, contingency, engineRun. |
| Ask gives a strange answer | web/js/features/ask.js → offline() (question parsing) and the tool list WRAPPED. Test with await ES.ask.offline("your question"). |
| Gemini mode fails | Ask → engine button → check the key note; errors fall back to offline and say why. Code: gemini() in ask.js. |
| Slow / laggy | Performance tab. Heavy work should be in workers (ES.jobs). Map redraws: world.js; 3D resolution adapts in globe.js. |
| Theme colours wrong | Tokens at the top of web/css/app.css (:root and :root[data-theme="dark"]). |
Handy console commands:
ES.store.get() // the whole app state
ES.store.set({ siteId: "malapert", view: "site" }) // drive the app
const S = ES.engine.site(-85.96, -3.27); // any point
ES.engine.windowStats(S, ES.util.nowJd(), 14) // the numbers every screen shows
ES.engine.next(S, ES.util.nowJd()) // next sunset / sunrise / Earthset / Earthrise
await ES.engine.terrainRange(-85.96, -3.27, ES.util.nowJd(), 365) // both terrain models
await ES.ask.offline("When should we land at Malapert?")Full list: docs/TROUBLESHOOTING.md.
| Check | Result |
|---|---|
| Sun direction vs NASA JPL Horizons | max error 0.0002° |
| Earth direction vs NASA JPL Horizons | max error 0.006° |
| Six published sunlight points (Bussey et al. 2010) | mean miss 3.7 points (calibrated on these points); held-out cross-validation 5.5 ± 3.8 points |
| Seven independent ridge points near Shackleton (Barker et al. 2021, 5 m, 2024–2025) | 80 m model 0.7–2.1 points above their deliberately conservative values |
| Connecting Ridge | 93.3% sunlight vs about 92% published (Gläser et al. 2014) |
| Shackleton crater floor | 0% sunlight: permanently dark, as published (Mazarico et al. 2011) |
Limitations are shown in the app (Method & accuracy) and in docs/VALIDATION.md: skylines away from the pole use a ~1.9 km global map; boulders and craters smaller than the terrain grid are not seen; site pins for some missions are approximate; results near ridges depend on exactly where a lander sets down, which is why both terrain models are shown.
Apple-inspired, calm and mature: neutral paper in light mode, true black in dark mode, one ink colour per meaning, used the same way everywhere:
| Meaning | Light | Dark / sky |
|---|---|---|
| Sun | #b8862b |
#f2b64a |
| Earth | #3f7f95 |
#7fb8c9 |
| Sun + Earth | #4d8f6b |
#8fcfa8 |
| Risk | #d4473d |
#ff6b5e |
System font stack (SF Pro / Inter fallback), sizes 12 / 15 / 19 / 24 / 30 / 48 px, 12–18 px radii,
maps and skies always dark. Motion is purposeful and switches off with prefers-reduced-motion. Details:
docs/DESIGN.md.
- Terrain: NASA LRO Lunar Orbiter Laser Altimeter (LOLA): south-pole 80 m and 240 m maps (PGDA product 90), global 16 px/degree map; NASA GSFC Shape-from-Shading 5 m terrain and LROC orthophotos for three Artemis candidate regions.
- Sun and Earth: NASA JPL SPICE, DE440 ephemeris and lunar orientation kernels.
- Imagery: NASA Scientific Visualization Studio (CGI Moon Kit), NASA Blue Marble, NASA SVS star maps.
- Sites: NASA NSSDCA landing-site list, NASA Artemis III candidate regions, mission publications
(sources per site in
web/data/sites.json). - Validation: Bussey et al. 2010 (Icarus 208), Barker et al. 2021 (Planetary and Space Science 203), Gläser et al. 2014, Mazarico et al. 2011 (Icarus 211).
NASA data is public domain. three.js is MIT. Moonset is MIT (see LICENSE).
- CLAUDE.md: rules and code map for anyone (human or AI) changing the code
- docs/ARCHITECTURE.md
- docs/DATA.md
- docs/VALIDATION.md
- docs/DESIGN.md
- docs/TROUBLESHOOTING.md
- pipeline/README.md