Files
sfhorizont/docs/SPECIFICATION.md
T

86 lines
8.3 KiB
Markdown
Raw Normal View History

2026-10-24 13:20:55 +02:00
# 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.
2026-10-25 07:11:03 +01:00
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.
2026-10-24 13:20:55 +02:00
## 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.
2026-10-25 07:11:03 +01:00
- **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.
2026-10-24 13:20:55 +02:00
- **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ő).