External observer with OpenCV UI baseline

step2_capture_inference_design.md

@@ -0,0 +1,104 @@
+# Step 2 - Disaccoppiamento Capture / Inference
+
+## Obiettivo
+
+Ridurre la serializzazione del loop principale separando:
+
+- acquisizione video e campionamento metadati;
+- inferenza, tracking e logica demo.
+
+Lo scopo non e' introdurre ancora una pipeline completa multi-processo stile ROS, ma togliere dal percorso critico almeno la parte `cap.read()` e la preparazione del pacchetto frame.
+
+## Vincolo architetturale
+
+Il frame consumato dall'inferenza non puo' essere un'immagine grezza isolata.
+
+Ogni frame deve essere rappresentato da un pacchetto logico di acquisizione che congela nello stesso istante:
+
+- `frame_id`
+- `timestamp`
+- `video_time_sec`
+- immagine
+- posa / stato del drone campionati nel momento di acquisizione
+
+Questo segue il modello gia' fissato nei documenti di architettura:
+
+- `capture` non inventa la posa;
+- `capture` la campiona dalla sorgente di stato disponibile;
+- `inference` consuma un `CapturedFrame` gia' coerente.
+
+Nel contesto della demo video attuale non esiste ancora una posa SLAM reale. Quindi il campo posa verra' popolato con una posa simulata minima, ma congelata all'acquisizione, utile a:
+
+- mantenere il contratto architetturale corretto;
+- evitare che in futuro frame e stato si disallineino;
+- propagare i metadati fino agli snapshot.
+
+## Struttura dati proposta
+
+```text
+CapturedFrame
+- frame_id
+- timestamp
+- video_time_sec
+- frame
+- pose
+```
+
+Dove `pose` e' un dizionario o struttura equivalente con almeno:
+
+- `mode`
+- `frame_id`
+- `video_time_sec`
+- `scan_direction`
+- `route_progress_ratio`
+
+Il campo `pose` potra' essere sostituito piu' avanti da un provider reale SLAM / PX4 / odometria senza cambiare il contratto tra capture e inference.
+
+## Strategia di esecuzione
+
+### Capture worker
+
+Un worker separato:
+
+- legge da `VideoCapture`
+- costruisce `CapturedFrame`
+- pubblica solo l'ultimo frame disponibile
+
+### Inference / control loop
+
+Il loop principale:
+
+- legge l'ultimo `CapturedFrame`
+- esegue YOLO, tracking e logica demo
+- usa sempre i metadati congelati nel pacchetto
+
+## Regola di coda
+
+La coda deve essere piccola:
+
+- niente backlog lungo;
+- meglio perdere frame che accumulare ritardo;
+- politica `latest frame wins`.
+
+## Impatto sul codice esistente
+
+### Nuove entita'
+
+- `CapturedFrame`
+- `CaptureWorker`
+- helper `sample_demo_pose(...)`
+
+### Oggetti da aggiornare
+
+- `CandidateSnapshot`
+- `NavigationSnapshot`
+- metadata snapshot JSON
+- observer telemetry, se utile, con riferimento alla posa dell'ultimo frame
+
+## Criteri di successo
+
+1. il core continua a produrre lo stesso comportamento funzionale della demo;
+2. inferenza e snapshot lavorano su frame con metadati coerenti;
+3. `cap.read()` non sta piu' nel loop principale critico;
+4. nessun backlog crescente;
+5. nessun blocco se il capture worker arriva piu' veloce o piu' lento del consumer.