flywms/step2_capture_inference_design.md

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

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.