Skip to content
MIGHTYASJEDPublic

About

Lunar south pole landing-site navigator: when are the Sun and Earth above the real horizon? Ray-traced NASA LOLA terrain, sunlight and Earth-view stats, mission planning.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Moonset

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.


Contents

  1. Quick start
  2. What it does
  3. How it works
  4. Repository layout
  5. Running, testing, formatting
  6. Hosting
  7. Debugging: where to look when something breaks
  8. Accuracy and validation
  9. Design system
  10. Data sources and credits
  11. Further docs

Quick start

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 start

Open http://localhost:8080. Use Chrome, Edge, Safari 16.4+ or Firefox 113+ (the app needs WebGL and DecompressionStream).

Opening web/index.html straight from disk (file://) does not work: browsers block the data downloads. Always use a server.


What it does

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.

How it works

Stack (and why)

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.

Architecture in one picture

             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.

Core ideas in the engine

  • 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.


Repository layout

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

Running, testing, formatting

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.


Hosting

The app is static files only: host the web/ folder anywhere.

GitHub Pages (included)

  1. Push the repo to GitHub (see the large-file note below).
  2. Settings → Pages → Source: GitHub Actions.
  3. Every push to main runs the engine tests, then publishes web/ (workflow: .github/workflows/ci.yml).

Other hosts

  • Netlify / Vercel / Cloudflare Pages: publish directory web, no build command.
  • Any server (nginx, Apache, S3): copy web/ and serve it. Serve .bin as application/octet-stream. Turn off on-the-fly compression for .bin files: they are already gzip.

Large files

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).


Debugging: where to look when something breaks

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.


Accuracy and validation

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.


Design system

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.


Data sources and credits

  • 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).


Further docs

About

Lunar south pole landing-site navigator: when are the Sun and Earth above the real horizon? Ray-traced NASA LOLA terrain, sunlight and Earth-view stats, mission planning.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages