Files
sfhorizont/docs/SPEC.md
T
2026-10-24 13:20:55 +02:00

93 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Product and screen spec
UI language: English (prepare for localisation; Hungarian likely next). Dark UI everywhere: capture happens in daylight but the app is also used next to the telescope at dusk. Phone portrait only. No fake status bar: respect safe areas.
## Flow
```
Sites ──New survey──▶ Setup ──Start capture──▶ Capture ──Finish──▶ Review ──Export──▶ Export
▲ └─tap finished site──────────────────────────────────────────▶ Review
│ └─tap in-progress site──────────────▶ Capture (resume)
└──────────────── close (X) from Capture / back from Setup
```
Data model (per site): name, location (lat, lon, elevation, GPS accuracy), north settings (declination, user offset), recorded session (frames + sensor stream), sky mask edits, derived horizon profile (alt per 1° az), export settings (margin, chosen formats).
---
## 1 · Sites (`design/screens/01-sites.png`)
Home screen listing surveyed sites.
- Header: title "Horizons", subtitle "Artificial horizons for NINA & Stellarium", settings icon button (44 px).
- Overline "SITES · n".
- **Site card** (tap opens Review for complete sites, Capture to resume in-progress ones):
- Name (19/600), coordinates in mono (12), chevron.
- Horizon sparkline: area + line of the profile, 0–40° altitude, x = azimuth 0–360 with N E S W N labels under it.
- Footer: "24 frames · full 360°" and chips for formats already exported (NINA, Stellarium) with a check icon.
- In-progress variant: "In progress" amber badge, sparkline only up to the covered azimuth with the remainder dashed, progress bar, "210° of 360° covered", "Continue survey" link.
- Bottom, fixed: primary "New horizon survey" (56 px, amber) and secondary "Import existing .hrz" (48 px, outline). Import parses a NINA file into a profile-only site (no panorama).
## 2 · Setup (`02-setup.png`)
- Back, title "New survey".
- Site name text input (prefilled with a suggestion).
- Location row: pin icon, lat/lon in mono, "112 m · GPS ±4 m", Refresh button. Allow manual edit on long-press (not drawn).
- North row: compass icon, "North from compass", "Declination +5.6° applied automatically". Declination comes from a magnetic model (WMM) evaluated at the GPS position and date, inside the core.
- "How to capture" illustration (ring around the phone, highlighted band, "sky not needed") and three numbered steps:
1. Stand where the telescope stands.
2. Hold the phone upright, tilted slightly above the horizon.
3. Turn once around slowly. Frames are taken automatically.
- Bottom primary: "Start capture". Request camera, motion/orientation and location permissions here (iOS web requires a user gesture for `DeviceOrientationEvent.requestPermission()`).
## 3 · Capture (`03-capture.png`)
Full-bleed camera preview (top 610 px), control panel below.
- Top bar over the camera: close (X → back to Sites, keeps progress), title chip "Backyard pier / frame 10 of 24", undo button (retake last frame).
- **Panorama progress strip** under the top bar: 24 cells over 0–360° with N E S W N labels. Captured part shows a mini preview of the detected silhouette; the next cell is outlined in the accent colour.
- Hint chip: "Turn right until the dot is in the circle" (auto mode) or "Line up the dot, then tap the shutter" (manual mode).
- **Live sky edge**: the detected sky/obstruction boundary is drawn as an accent line on the preview, so the user sees what will become transparent.
- **Targeting**: fixed white circle in the centre. The accent dot shows where the next frame's target is, relative to the current orientation, with a dashed leader. When the dot is inside the circle, the tilt is within tolerance and the phone is steady, the frame is taken automatically (see ARCHITECTURE: auto-shutter).
- 0° horizon reference line with label (dashed).
- **"Tree reaches the frame top at 125°"** warning bar with "Add higher shot": shown when obstruction touches the top edge of a frame. It asks for one extra frame at that azimuth tilted higher (about +35°). Coverage then extends upward locally.
- Readouts: HEADING (true, degrees), TILT (target +10°, blue when within tolerance), COVERS (vertical coverage of the current frame, e.g. "−22…+42°").
- Controls: "Auto on/off" toggle (left), shutter (80 px ring, always usable manually), "Finish" (right, goes to Review; allowed with partial coverage, which is then shown as in-progress).
- Haptic tick on each auto capture. Keep the screen awake.
## 4 · Review (`04a-review-nina-horizon.png`, `04b-review-panorama-mask.png`)
Two tabs. "NINA horizon" is the default.
**NINA horizon tab**
- Profile chart: x = azimuth 0–360 (N E S W N), y = altitude 0–40°. Filled area + solid accent line = detected sky edge. Dashed blue line = what is written to `.hrz` (edge + margin).
- Legend under the chart.
- **Safety margin** slider 0–5° in 0.5° steps (default +2.0°). Caption: "Keeps NINA targets clear of tree tips and compass error". Updates the dashed line live.
**Panorama tab**
- Zoomed panorama (pan and pinch): checkered = transparent sky, photo = obstruction, accent line = edge.
- Overview strip of the whole 360° with the viewport outlined (drag it to navigate).
- Legend: "Transparent sky in Stellarium".
- Mask tools: "Auto edge" (default; tap re-runs detection locally), "Paint sky", "Paint ground". Brush shows as a dashed circle; brush size by pinch or a later setting. Strokes are stored as edits, not baked pixels, so detection can be re-run.
**Both tabs**
- **North offset** row: −/+ in 0.5° steps, "Applies to .hrz and panorama". Rotates the whole result if a known object sits off.
- Primary "Export".
## 5 · Export (`05a-export-hrz.png`, `05b-export-landscape-ini.png`)
- Subtitle summarises settings: "Backyard pier · margin +2.0° · north offset 0.0°".
- Format cards (checkbox + title + extension badge + description), selected card has an accent border:
1. **NINA custom horizon** `.hrz`, on by default.
2. **Stellarium panorama** `.zip`, on by default if the panorama is complete: spherical landscape, 8192 × 2048 PNG with transparent sky.
3. **Stellarium outline only** `.zip`, off by default: polygonal landscape.
- Preview with tabs `.hrz` / `landscape.ini` (mono, scrollable).
- Help text: "NINA: Options › General › Astrometry › Custom Horizon. Stellarium: install the .zip under Sky and viewing options › Landscape › Add/remove landscapes."
- Buttons: "Save" (to device files) and primary "Share n files" (system share sheet).
## Copy and units
- Degrees with one decimal in readouts and files (`137.4°`), azimuth 0–360 clockwise from true north.
- Use the minus sign `−` in UI, ASCII `-` in files.
- Numbers in IBM Plex Mono, everything else in Barlow.