Files
sfhorizont/docs/SPECIFICATION.md
T
2026-10-25 07:11:03 +01:00

86 lines
8.3 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.
# SkyContour (sfzenith) — projektállapot és döntések
*Frissítve: 2026-10-23. Ez a fájl a v1.0-s (2026-07-16) specifikációt váltja.*
## Irányadó dokumentumok
A 2026-10-23-as designer-átadás az irányadó. Ha ez a fájl és az alábbiak ellentmondanak, az alábbiak nyernek:
| Fájl | Tartalom |
|---|---|
| [README.md](README.md) | Az átadás áttekintése, olvasási sorrend |
| [SPEC.md](SPEC.md) | Képernyők (Sites → Setup → Capture → Review → Export), viselkedés, szövegek |
| [ARCHITECTURE.md](ARCHITECTURE.md) | WASM mag + vékony platform-adapterek, core API, algoritmusok, felvett session formátuma |
| [FORMATS.md](FORMATS.md) | `.hrz`, Stellarium spherical/polygonal pontos formátuma |
| [design/](design/) | Tokenek, képernyő-PNG-k (390×844 @2x), HTML forrás |
| [examples/](examples/) | Minta kimenetek és minta session; a core golden tesztjei ezekhez mérnek |
Ez a fájl csak a projekt-szintű döntéseket, az aktuális állapotot és a nyitott kérdéseket tartja nyilván.
## Döntések (változások a v1.0 spechez képest)
1. **Felvétel módja.** A célkeresztes kézi pontfelvétel helyett automatikus exponálás: 24 kép, 15°-onként, +10°-os dőlésnél, stabil tartásnál. Képenként ég/akadály-felismerés, a horizont az oszloponkénti legmagasabb nem-ég pixel. A kézi exponálás tartalékként megmarad.
2. **Észak.** Iránytű + deklináció (WMM, a magban) + a felhasználó kézi észak-eltolása a Review képernyőn. A Nap- vagy csillag-alapú igazítás **elvetve**; a pontatlanságot a biztonsági ráhagyás nyeli el (alapból +2°, 0–5°).
3. **Stellarium export.** `type = spherical`, 8192×2048-as sáv `maptex_top`/`maptex_bottom` értékekkel (nem teljes gömb). A kép bal széle Kelet (90°). Az észak-eltolás a képbe van beégetve, `angle_rotatez = 0`. Mellé jön a csak körvonalas `polygonal` változat is.
4. **Orientáció.** Hosszabb távon kvaternió (ENU). A jelenlegi kód alpha/beta/gamma forgatásmátrixa (`core/src/projection.rs`) már teljes 3D-s, a régi `beta − 90` képlet nincs használatban.
5. **Platform.** A webes UI fut böngészőben és az app WebView-jában is. A Flutter csak vékony natív héj (Android kész). Natív kamera-adapter csak akkor lesz, ha a webes korlátok (pl. expozíció-zár) miatt muszáj. A v1.0 flutter_rust_bridge-terve ezzel **kikerült**.
6. **Fejlesztési mód.** A telefonon felvett session (`session.json` + `sensors.jsonl` + képkockák) asztali böngészőben és unit tesztekben visszajátszható. A felismerés és a varrás finomhangolása így telepítés nélkül megy.
7. **Név és azonosító** (2026-10-24): az app neve **SkyContour** (a „Horizon(s)” név mindkét áruházban túlzsúfolt, és két közvetlen iOS-versenytárs is használja). App-azonosító: Android `com.sagifer.skycontour`, iOS `com.sagifer.skycontour.ios` (a sima azonosítót egy korábbi ingyenes Personal Team-es telepítés lefoglalta). iOS-aláírás: egyéni fejlesztői fiók, Team ID `8EQZ487TY9`. A kódnév (sfzenith) belül marad: Dart-csomag, Rust crate, tárolókulcsok.
## A v1.0-ból érvényben marad
- **FOV-források sorrendje**: mért (élő kalibráció két átfedő képből, már működik) → eszköztábla → kézi → alapérték. A forrás a sessionben `device.camera.fovSource` néven tárolódik.
- **Secure origin**: kamera és szenzor csak HTTPS vagy `localhost` alól érhető el. Fejlesztéshez marad a `wasm/serve.py` / Vite basic-ssl; a natív héj `http://localhost:47391`-et szolgál ki (lib/local_server.dart). A port a tárolási origin része: a helyszínek a localStorage/IndexedDB-ben ehhez kötődnek, kiadás után nem szabad változtatni.
- **iOS 13+**: a `DeviceOrientationEvent.requestPermission()` csak felhasználói gesztusból hívható (a Setup „Start capture” gombján).
- **Offline működés**: a WMM-együtthatók és a betűtípusok (Barlow, IBM Plex Mono) a buildbe ágyazva, CDN nélkül.
- **Csak álló tájolás**, a képernyő ébren tartása felvétel közben.
## Jelenlegi állapot
**Kész**
- `core/` (`sfzenith-core`): tiszta Rust, web-sys nélkül, `cargo test`-tel natívan tesztelve.
- `profile`: 360 értékes horizontprofil, pontokból interpolálás (0/360 átfordulással), észak-eltolás, medián simítás.
- `hrz`: NINA export (ráhagyással) és import.
- `stellarium`: `landscape.ini` (spherical/polygonal), `horizon.txt`, panoráma-renderelés Stellarium-elrendezésbe (Kelet balra, ég átlátszó), PNG.
- `zip`: determinisztikus zip-író.
- `session`: a felvett session-csomag formátuma.
- `skymask`: ég/akadály-maszk a varrt sávon (ég-növesztés a fotók tetejéről, illesztési varratok és lebegő „felhők” kiszűrése), ecsetes javítások, ebből a horizontprofil, a lefedettség és a top-touch jelzés.
- `projection`, `fov`: a korábbi wasm crate-ből átköltöztetve.
- Golden tesztek: a kimenet bájtra egyezik a `docs/examples/` fájljaival.
- `wasm/`: vékony wasm-bindgen adapter (kamera, canvas, szenzorok) és a core exportjainak JS-felülete (`export_hrz`, `parse_hrz`, `export_stellarium_spherical`, `export_stellarium_polygonal`, `landscape_ini`, `profile_from_points`, …).
- `wasm/frontend/`: az új UI mind az 5 képernyővel a design tokenekkel, plusz Settings (FOV, szerző) és FOV-kalibráló képernyő.
- Capture: célzópont, automatikus exponálás, 24 cellás haladásjelző a varrt sávból, visszavonás, „Add higher shot”, ébren tartott képernyő.
- Review: profil + ráhagyás, panoráma ecsettel, észak-eltolás.
- Export: `.hrz`, Stellarium spherical/polygonal zip, előnézet, mentés/megosztás.
- Sites: lista, folytatás, `.hrz` import.
- Tárolás: a helyszínek localStorage-ban, a varrt sáv PNG-ként IndexedDB-ben.
- Asztali teszt: `?sim` (nyilakkal forgatható szimulált iránytű).
- Flutter iOS-héj: engedély-szövegek, álló tájolás, iOS 15+, mentés a Fájlok appba (natív csatorna), telepítés: `scripts/install_ios.sh`.
- Flutter Android-héj (`lib/main.dart`): WebView, kamera- és helyengedély, GPS a WebView-nak, mentés a Letöltések mappába (natív csatorna), megosztás (share_plus), álló tájolás, a rendszersávok mellett marad (SafeArea), a Vissza gomb a webes navigációt lépteti. Emulátoron (Pixel 9a, Android 16) végigpróbálva.
- Többnyelvűség: a felület a rendszer nyelvét követi (angol, spanyol, arab – jobbról balra –, német, magyar, lengyel, francia, olasz, szlovák), a Settingsben kézzel is választható; a natív tab bar és az iOS-engedélyszövegek is fordítva. Az exportált fájlok angolok maradnak.
- Közös natív szolgáltatások mindkét héjban: képernyő ébren tartása felvétel közben (wakelock_plus), rezgés exponáláskor, app-ikon (A · Skyline) és natív nyitókép.
**Még nincs**
- Képenkénti ég-felismerés és élő égvonal a kameraképen: most a felismerés a kész, varrt sávon fut.
- Varrás erősítés-kiegyenlítéssel (a mostani sáv vetítés alapú, „utolsó nyer”).
- Dőlés (roll) ellenőrzése az automatikus exponálásnál.
- WMM deklináció.
- Session felvétele, mentése és visszajátszása.
## Ütemterv
| # | Tartalom | Állapot |
|---|---|---|
| 1 | Core: profil, `.hrz`, Stellarium exportok, session-formátum, golden tesztek | ✅ kész |
| 2 | Új React UI az 5 képernyővel, tokenekkel, a core exportokra kötve. A 4. pontból előrehozva: automatikus exponálás, ég-maszk a varrt sávon, ecsetes javítás, top-touch | ✅ kész (telefonon még tesztelendő) |
| 3 | Session felvétele a telefonon, visszajátszó adapter asztali böngészőben | következő |
| 4 | Ég-felismerés képenként, élő égvonal a kameraképen, finomhangolás valódi felvételeken | |
| 5 | WMM deklináció, varrás erősítés-kiegyenlítéssel | |
| 6 | Fordítások (en, es, ar, de, hu, pl, fr, it, sk – kész), polírozás (az iOS-héj előrehozva, kész) | |
## Nyitott kérdések
- **Stellarium zip telepítés**: a zip egy almappában (`<id>/landscape.ini`) tartalmazza a fájlokat. Egyszer ki kell próbálni a Stellarium „Add/remove landscapes” telepítőjével.
- **NINA**: el kell fogadnia a `# Az Alt` fejlécet és a `.` tizedesjelet nem angol nyelvű Windowson is. Kiadás előtt egyszer tesztelni kell.
- **Panoráma memória**: a 8192×2048-as RGBA kép ~64 MB a wasm memóriában. Gyenge telefonon kellhet egy 4096×1024-es opció (az exporter már paraméterezhető).