PRD-005 — Earth Orbit Viewer

Status · Draft v0.1 Sources · 02_Project_Concept.md §six-screens · 03_Data_Catalog.md §earth-objects Audiences · curious learner, STEM student (PA §audiences) Promises · real physics, educational at every level (PA §promises) Principles · physics first (PA §principles) Why this is a PRD · This screen changes a person's understanding of how much humanity has already placed around Earth — and makes the logarithmic range of orbital distances viscerally legible in a way that a list of altitudes never does.

A person who knows the ISS is "in space" but has never thought about where JWST is opens this screen. The ISS is at the bottom, close to Earth. The Moon is about two-thirds of the way up. JWST is near the top. The L2 label explains: 1.5 million kilometres. They look back at the ISS: 408 km. The ratio is 3,750 to 1. On a linear scale, the ISS would be invisible. The logarithmic scale makes both legible. They understand something new.

The problem

"Space" is treated as a single location. The ISS, GPS satellites, geostationary TV satellites, the Moon, and JWST are all "in space" — but they occupy regions of near-Earth space that differ by four orders of magnitude in altitude. The vocabulary exists (LEO, MEO, GEO, cislunar, L2) but the spatial relationship is invisible.

The experience

The screen shows a vertical logarithmic scale. Earth is at the bottom. Objects are positioned at their correct relative altitudes. The regimes are labelled — Low Earth Orbit, Medium Earth Orbit, Geostationary, Cislunar, L2. The ISS, Hubble, GPS constellation, geostationary belt, the Moon, and JWST are all present.

The user clicks on JWST. A detail panel opens: altitude 1.5 million km, orbital period 365 days (it orbits the Sun, not Earth, in a halo orbit around L2), primary mirror 6.5m, launch date December 2021. The LEARN tab links to the JWST mission page, the mirror deployment story, and the first light images.

The user hovers over the geostationary belt. A label explains: at 35,786 km, a satellite's orbital period matches Earth's rotation. That's why TV satellites are stationary in the sky.

Why now

Earth orbit is the context screen — it shows what's already there before humanity tries to go further. It pairs with the Moon Map (what's on the lunar surface) to establish the full picture of where humanity has placed hardware.

Success looks like

A user correctly explains why geostationary satellites are at 35,786 km and not higher or lower after using this screen.

A user is surprised to discover that JWST is not in Earth orbit at all — it's at a Lagrange point 1.5 million km away — and that discovery changes their understanding of what "Webb telescope" means.

Out of scope

• Orbital mechanics simulation (objects don't move — this is a static reference view)
• Debris cloud or Kessler syndrome visualisation
• Live satellite tracking (TLE data)
• Objects below ISS altitude (suborbital flights)

The sharpest threat

The logarithmic scale is the screen's core insight. If it isn't labelled clearly enough that a first-time user understands why the scale is non-linear, the screen looks like a random arrangement of dots rather than a carefully scaled diagram.

Open threads

• UXS-005 for full visual contract
• Earth objects data from data/earth-objects.json (RFC-002 adjacent — same data model questions apply)

Links

• Prototype: docs/prototypes/P05_earth-orbit.html
• Concept: docs/concept/02_Project_Concept.md §six-screens

---

Extension — GALLERY + LEARN tabs (v0.1.10)

Status · Decided · shipped 2026-05-02

The detail panel that opens when an Earth object is clicked now exposes three tabs (OVERVIEW · GALLERY · LEARN) instead of a single content block:

• GALLERY — NASA Images API photos for ISS, Hubble, JWST, Chandra, GPS, GEO, etc. (5 photos per object where available); Wikimedia Commons fallback for non-NASA constellations (Galileo, GLONASS, BeiDou). 39 photos total across 13 entities. LRO copies its 5 photos from images/missions/lro/ to avoid duplicate downloads. Two entries (tiangong, gaia) stayed empty — Wikimedia filenames not findable; their GALLERY tabs stay hidden per the honesty rule.
• LEARN — already-curated links[] array in the base earth-object record (intro/core/deep tiers) is now surfaced. ISS deep links to NASA's facts-and-figures page; Hubble deep links to a peer-reviewed paper; etc.

Why it matters: PRD-005's "logarithmic scale" insight makes the geometry legible. The GALLERY tab makes the objects legible — a person who has seen the ISS dot at 408 km can now see the ISS itself in a photo. The LEARN tab is their next-step doorway.

Honesty rule: entities without photos render no GALLERY tab. Entities without links[] render no LEARN tab. No empty states with placeholder text.