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

8.3 KiB
Raw Blame History

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 Az átadás áttekintése, olvasási sorrend
SPEC.md Képernyők (Sites → Setup → Capture → Review → Export), viselkedés, szövegek
ARCHITECTURE.md WASM mag + vékony platform-adapterek, core API, algoritmusok, felvett session formátuma
FORMATS.md .hrz, Stellarium spherical/polygonal pontos formátuma
design/ Tokenek, képernyő-PNG-k (390×844 @2x), HTML forrás
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ő).