# Quizzman Astro — Sky Viewer (detailed)

- Markdown: https://astro.quizzman.com/about-sky-viewer.md
- Live UI: https://astro.quizzman.com/sky-viewer
- Product overview: https://astro.quizzman.com/about.md
- API behind the UI: `GET /viewer/sky` → https://astro.quizzman.com/about-api.md
- Human guide: https://astro.quizzman.com/guide/SKY_VIEWER.md

## One-sentence definition

**Sky Viewer** is Quizzman Astro’s interactive planetarium: a browser UI that loads a full sky frame from `/viewer/sky` and renders **2D stereographic**, **3D celestial sphere**, or **Explorer** (any-body-centric solar system) views.

## What you can do

1. **Observe from Earth** — Alt/Az sky for a geographic observer (lat/lon), local civil time or JD.  
2. **Change Observation Center** — Earth, Sun, Moon, Mercury…Neptune; non-Earth centers open Explorer.  
3. **Inspect objects** — click stars/planets for magnitude, RA/Dec, Az/Alt, rise/transit/set.  
4. **Toggle layers** — orbits, constellations, DSO, ISS, astrology; grids (equator, ecliptic, galactic, horizon, meridian, RA, Dec).  
5. **Workbench** — Overview · Observer · Time · Selected · Coordinates · Engine Debug.  
6. **Learn terms** — glossary link (VI/EN/繁中) for beginners.

## Modes

| Mode | When | What you see |
|------|------|----------------|
| **2D** | Default Earth center | Stereographic sky map; pan / zoom; pick objects |
| **3D** | Earth center | Celestial sphere + OrbitControls; detailed body globes |
| **Explorer** | Center ≠ Earth | Relative ecliptic map in AU + 3D orbits; 1 AU scale bar |

FOV minimum is **15°** so the map never collapses to an empty telephoto frame.

## Controls (keyboard / pointer)

| Action | Input |
|--------|--------|
| Pan | Drag |
| Zoom | Wheel · pinch · slider · `+` / `-` / `0` |
| Hide UI | `H` |
| Settings panel | `Ctrl+[` |
| Workbench panel | `Ctrl+]` |
| Search | Toolbar Search |
| Fullscreen | Toolbar Full |

## Data pipeline (how the tool works)

```text
User picks date/time + lat/lon (+ center)
        │
        ▼
GET /astro/day-sky?date=&timezone=&longitude=   ← civil almanac (optional first hop)
        │
        ▼
GET /viewer/sky?jd=&lat=&lon=&magLimit=&center=&zodiac=
        │
        ▼
JSON frame: sun, moon, planets, stars, dso, iss, grids, explorer, ephemeris_backend
        │
        ▼
Canvas render (2D / 3D / Explorer) + HUD / workbench
```

### Important query parameters (`/viewer/sky`)

| Param | Role |
|-------|------|
| `jd` | Julian Day (UT) |
| `lat`, `lon` | Observer (degrees) |
| `magLimit` | Star cutoff (default ~4) |
| `center` | `earth` \| `sun` \| `moon` \| planet id |
| `zodiac` | `tropical` \| `sidereal` |
| `az`, `alt`, `fov` | Camera when server projects |

### Response fields agents care about

- `ephemeris_backend` — `de440` when SPK covers JD, else analytical/keplerian fallback  
- `sun` / `moon` / `planets[]` — sky angles  
- `stars[]` — catalog subset by magnitude  
- `explorer.bodies[]` — `{ id, x, y, z, distance_au, is_center }` in explorer ecliptic frame  
- Time scales and observer block for debugging  

## Explorer mode (any-body center)

Centers: `earth` · `sun` · `moon` · `mercury` · `venus` · `mars` · `jupiter` · `saturn` · `uranus` · `neptune`

Example:

```bash
curl -s 'https://astro.quizzman.com/viewer/sky?jd=2460000.5&lat=10.82&lon=106.63&magLimit=4&center=mars' \
  | head -c 600
```

Notes for accurate AI answers:

- Distances use true AU spacing; drawn radii are slightly exaggerated for readability.  
- Stars and local horizon quantities remain **Earth-observer** based.  
- “Sky as seen from Mars’ surface” (local horizon on Mars) is **not** claimed — Explorer is the coordinate foundation.

## Layers & overlays

- **Bodies:** Sun, Moon, planets, bright stars, DSO catalog, ISS from TLE  
- **Lines:** constellation stick figures; orbit traces  
- **Grids:** celestial equator, ecliptic, galactic, horizon, meridian, RA/Dec  
- **Astrology:** optional zodiac overlay (`tropical` / `sidereal`)

## Beginner glossary (same product)

| Lang | URL |
|------|-----|
| VI | https://astro.quizzman.com/glossary |
| EN | https://astro.quizzman.com/glossary-en |
| 繁中 | https://astro.quizzman.com/glossary-zht |

Topics: Alt/Az, RA/Dec, ecliptic (λ,β), degrees/arcmin/arcsec, UTC/TT/ΔT/JD/sidereal time, magnitude, 88 IAU constellations.

## Related Lab UI

Lab also hosts a Sky Viewer entry at https://lab.quizzman.com/tool/sky-viewer — for the **engine host and canonical viewer**, cite **https://astro.quizzman.com/sky-viewer**.

## What Sky Viewer is not

- Not a game / AR toy without ephemeris backing  
- Not an LLM drawing random stars  
- Not a full professional observatory control system (no telescope pointing protocol)