# Computer vision, traiettorie e replay annotati Aggiornato il 17 ottobre 2026. Documento di progetto collegato a [esplora.html](esplora.html#visione-replay), alla [ricerca sulle camere](ricerca-videocamere.md) e al [confronto Pi 4 / Pi 5](ricerca-raspberry-video.md). ## Stato e obiettivo L’utente vuole valutare computer vision per seguire il disco e disegnare traiettorie nei replay, oltre a commento e statistiche mediante AI esterna. Questo documento registra l’architettura proposta nella discussione. **Non sono stati implementati tracker, inferenza neurale, acquisizione reale, overlay sui video reali o misure delle prestazioni.** Il film CAD esistente è una coreografia virtuale e non fornisce una prova della visione. Obiettivo di lavoro: camera fissa sopra il campo 800 × 400 mm, disco Ø44 mm, acquisizione 720p a 120 immagini/s; conservare almeno 5 s prima del gol e 2 s dopo. Il frame rate effettivo deve essere verificato. Campo visivo e qualità dipendono dalla camera e dal ritaglio del modo veloce: non confondere la proposta ottica generica del CAD con le caratteristiche della camera acquistata. Richieste confermate: ripresa, analisi dei tiri, commento/statistiche e replay con possibilità di sovrapporre traiettorie. Il 17 ottobre l’utente approva Raspberry come host del display replay a colori, con 10,1″ come prima variante e confronto13,3″. Restano proposti modello Pi, Python, OpenCV, camera USB, algoritmo di tracking e luogo dell’inferenza. EL-01 e BOM mantengono la base storica a due ESP32; nuove varianti CAD dedicate illustrano display e ingombro camera USB generico senza dichiarare una migrazione firmware completata. [Decisione e limiti](adr/0003-display-frontale-replay.md). ## Architettura proposta ```text camera e timestamp ──→ acquisizione nativa ──→ buffer video compresso │ │ │ └─→ replay originale └─→ tracking ──→ posizioni e confidenza │ sensori porte ──→ eventi gol/punteggio ─────────────────┤ ├─→ replay web con overlay ├─→ esportazione MP4 annotato └─→ statistiche e AI esterna ``` Il video originale resta indipendente dall’analisi. Le posizioni sono salvate in un file separato, associato alla clip: si possono correggere un algoritmo o un colore senza alterare il filmato. Python coordina configurazione, eventi, code e salvataggi; acquisizione, codec ed elaborazioni sulle immagini sfruttano strumenti e librerie native. La pipeline USB UVC non è automaticamente la stessa della camera CSI/Picamera2. ### Proposta di componenti software | Parte | Strumento proposto | Funzione | |---|---|---| | Acquisizione CSI | libcamera / rpicam oppure Picamera2 | Modalità sensore, esposizione, timestamp, buffer codificato | | Acquisizione USB UVC | Pipeline nativa compatibile con il formato effettivo, per esempio GStreamer | Ricezione MJPEG e buffer senza ricodifica continua | | Coordinamento | Python | Stato partita, richiesta salvataggio, gestione dei lavori e configurazione | | Visione iniziale | OpenCV | Calibrazione, rilevamento per colore/forma e tracking | | Replay consultabile | HTML video + Canvas | Disegno sincronizzato di scie, misure ed eventi, attivabili separatamente | | Esportazione | OpenCV e FFmpeg oppure GStreamer | Rendering ed encoding di un MP4 con grafica incorporata | | AI esterna | Adattatore al servizio da scegliere | Commento e interpretazione di eventi/statistiche e sequenze utili | Non sono dipendenze già installate sul dispositivo finale e non esiste ancora un servizio avviato. Le librerie vanno selezionate nelle versioni compatibili con sistema, camera e modalità reali. ## 1. Calibrare prima di misurare 1. Bloccare montante e camera; scegliere il modo a 120 fps e verificare tutti e quattro gli angoli del campo. Una calibrazione del modo a piena risoluzione non corregge automaticamente un diverso ritaglio. 2. Stimare la distorsione della lente con una procedura di calibrazione e conservare i parametri della camera. Per una wide verificare se il modello ottico scelto descrive sufficientemente la distorsione. 3. Associare i quattro angoli del campo alle quote reali, ottenendo una trasformazione prospettica per il piano. Le coordinate del progetto possono coincidere con il CAD: X da −400 a +400 mm e Y da −200 a +200 mm, centro campo (0,0). 4. Salvare risoluzione, crop, orientamento, eventuali correzioni e identificativo della calibrazione. Verificare punti noti anche al centro e ai bordi, non soltanto i quattro angoli usati per la trasformazione. 5. Per disegnare sull’originale, ritrasformare correttamente le posizioni nello spazio dei pixel del video; in alternativa visualizzare il video già corretto. Non sovrapporre coordinate di immagini rettificate a un video ancora distorto. Una camera spostata, una nuova ottica o una diversa modalità richiedono una verifica della calibrazione. La trasformazione del piano è adatta alla posizione del disco vicino al piano; non ricava automaticamente la posizione tridimensionale delle mani o della parte alta dei battitori. ## 2. Tracking con OpenCV come primo tentativo Il campo fisso, la geometria nota e un disco di colore ben distinguibile consentono di provare prima una soluzione di computer vision classica, senza addestramento di una rete neurale: - limitare l’analisi alla regione del campo e alle zone porta pertinenti; - cercare candidati mediante intervalli di colore HSV, area e forma compatibili con il disco nella vista scelta; - filtrare il rumore e usare i contorni per stimare il centro, senza assumere che ogni oggetto giallo sia il disco; - associare le rilevazioni nel tempo con limiti plausibili di spostamento, aggiornati in base ai timestamp reali; - stimare posizione e velocità con un filtro appropriato, per esempio Kalman, mantenendo l’incertezza; - distinguere disco, battitori e mani: contatti e rimbalzi non vanno identificati dal solo cambio di colore o da un singolo frame. Non si presume che questa soluzione sia già robusta con riflessi, strisce RGB animate e occlusioni. Esposizione breve, fuoco stabile e illuminazione bianca costante restano parte della soluzione. Durante il tuning usare video rappresentativi, compresi tiri veloci, battitori sovrapposti al disco e cambi di luce. ### Traccia osservata, prevista e sconosciuta Una rilevazione è una misura dell’immagine; il filtro può prevedere dove dovrebbe trovarsi il disco, ma la previsione non è un’osservazione. Proposta grafica: - linea continua per tratti sostenuti da rilevazioni affidabili; - linea tratteggiata per brevi previsioni, con limite di durata e confidenza; - interruzione della traccia quando il disco resta nascosto o il collegamento non è affidabile. Non congiungere automaticamente due posizioni lontane attraverso una lunga occlusione: nel frattempo potrebbero essere avvenuti un rimbalzo o un colpo. Un Kalman a velocità costante va gestito in modo appropriato vicino agli urti, altrimenti può arrotondare il cambio di direzione e falsare la misura. Velocità e punti di impatto sono stime, da mostrare con la loro attendibilità. I gol restano determinati dalle barriere IR nelle porte, con correzione manuale disponibile. ## 3. Dati da associare al replay | Dato | Significato e criterio | |---|---| | Clip e frame | Identificativo della registrazione e indice del frame, senza assumere assenza di perdite | | Tempo di acquisizione | Timestamp della camera/pipeline, oltre al tempo nel video; non usare il solo istante di ricezione del pacchetto | | Posizione pixel | Centro rilevato e spazio immagine in cui è espresso: originale, corretto o rettificato | | Posizione metrica | X e Y in mm nel campo calibrato, con riferimento alla versione della calibrazione | | Stato del tracking | Osservato, previsto o perso; qualità/confidenza con criterio da definire | | Velocità stimata | Vettore e modulo da posizioni metriche e intervalli temporali reali; non da fps nominali | | Eventi | Gol da sensore, correzione manuale, possibili colpi/rimbalzi derivati dal tracker, separati per origine | JSON è un possibile formato del file associato, non una decisione vincolante. Conservare parametri dell’algoritmo e versione della calibrazione permette di rielaborare lo stesso video e confrontare i risultati. Timestamp dei sensori e della camera devono essere messi in relazione mediante un riferimento temporale comune o un offset stimato. Per CSI e USB occorre verificare cosa rappresenti il timestamp disponibile e la sua relazione con il tempo di esposizione. Il clock del replay rallentato non è il tempo fisico usato per misurare la velocità del disco. ## 4. Grafica nel replay web Un elemento video mostra il filmato, un Canvas sovrapposto disegna i dati al tempo corrispondente. Funzioni proposte: - scia breve dietro il disco, con lunghezza temporale regolabile; - traiettoria del tiro o dello scambio completo; - frecce di movimento e velocità stimata, con unità; - marcatori di rimbalzi/colpi stimati e gol da sensore; - mappa delle zone attraversate, accumulata soltanto dalle osservazioni idonee; - indicazione di tratto incerto, disco perso e intervalli con frame mancanti; - pulsanti per attivare scia, traiettoria, velocità ed eventi separatamente. La grafica segue il tempo media e deve aggiornarsi anche con pausa, seek, cambio velocità e ridimensionamento della finestra. Non guidarla soltanto con un timer indipendente. A 120 fps una clip reale di 7 s contiene circa 840 osservazioni se non si perdono immagini; a 30 fps in rallentatore 4× dura 28 s. I punti sono associati ai timestamp originali e al montaggio del replay, non a un semplice contatore di fotogrammi del display. Non è necessario riprodurre o inferire 120 fotogrammi al secondo in un browser per ottenere un replay lento fluido a 30 fps. L’acquisizione resta a 120 per conservare il dettaglio temporale. ## 5. MP4 con traiettorie incorporate Il replay web mantiene grafica e video separati e consente di modificare la visualizzazione senza ricodificare. Per condividere un file unico, un lavoro separato combina frame e overlay e produce un MP4 annotato: 1. selezionare clip, intervallo e dati di tracking; 2. scegliere rallentamento, risoluzione e grafica; 3. disegnare punti/linee/testi nelle coordinate corrette; 4. codificare il file e verificare sincronizzazione, durata e leggibilità. OpenCV può comporre la grafica sui frame; FFmpeg può gestire il video finale. GStreamer offre elementi di overlay, incluso cairooverlay, utili per una pipeline integrata. Tempi e codec vanno misurati: una esportazione in differita non è una promessa di rendering live a 120 fps. Conservare sempre l’originale e la traccia dati per correzioni future. ## 6. Quando introdurre una rete neurale Se le prove mostrano che colore/forma non bastano, valutare un rilevatore leggero addestrato su immagini del nostro campo. Servono dati annotati che coprano tiri, luci, riflessi, mani, battitori, disco parzialmente nascosto e casi negativi. Separare dati di addestramento e verifica per partite/condizioni, evitando di valutare soltanto frame quasi identici a quelli usati per addestrare. Il rilevatore identifica gli oggetti; il tracker collega le posizioni nel tempo. Un modello generico di object detection non va considerato già capace di riconoscere il nostro disco. Training e misurazione delle prestazioni possono avvenire su PC; la distribuzione si sceglie dopo aver misurato accuratezza, velocità e carico della pipeline completa. Opzioni aperte: - PC/server esterno per tracking più impegnativo o modelli neurali; - Pi 5 per più margine CPU locale; - Pi 5 con AI HAT+ / Hailo per modelli e operatori supportati, verificando conversione e integrazione; - Pi 4 per primo tentativo OpenCV e/o elaborazione del replay in differita. L’AI HAT+ non riconosce automaticamente il disco: accelera inferenza di modelli compatibili. La velocità del solo modello o il dato TOPS non certificano 120 fps end-to-end, che includono acquisizione, decodifica, preprocessing, tracking, rendering e rete. Commento e statistiche dell’AI esterna sono un compito diverso dal tracking: possono ricevere eventi, misure e brevi sequenze selezionate, senza inviare tutte le 120 immagini/s a un grande modello linguistico/visivo. Il risultato del tracker non deve inventare informazioni mancanti per alimentare il commento. ## 7. Pi 4, Pi 5 o PC: proposta di sviluppo | Obiettivo | Prima configurazione da provare | Limite da verificare | |---|---|---| | Replay originale 720p120 e traccia in differita | Pi 4 da 4 GB, OpenCV e acquisizione nativa disaccoppiata | Tempo di analisi e salvataggio mentre la partita continua | | Overlay consultabile su telefono/PC | Video + dati + Canvas nel browser del dispositivo di visione | Sincronizzazione con il tempo video e carico del client | | Traccia live e analisi locale più impegnativa | Pi 5, con pipeline e risoluzione di analisi ottimizzate | Frame effettivi, latenza, temperatura e risposta ai gol | | Inferenza neurale impegnativa | PC esterno o Pi 5 con acceleratore e modello compatibile | Accuratezza e prestazioni end-to-end | La proposta iniziale è **registrare tutti i frame disponibili e analizzare il replay dopo il gol**: l’analisi può essere più lenta della cattura senza perdere immagini già salvate. Non garantisce che il replay annotato sia disponibile immediatamente. Pi 5 non è obbligatorio per disegnare traiettorie; è una scelta di margine se si vuole più lavoro locale. Neppure Pi 5 garantisce automaticamente inferenza neurale su ogni frame a 120 fps. ## 8. Verifiche di accettazione ancora da eseguire 1. Riprendere clip reali e verificare timestamp, frame persi, nitidezza, copertura e comportamento con luci RGB. 2. Annotare manualmente un campione di posizioni ed eventi come riferimento; misurare errore in pixel/mm, rilevazioni errate, disco perso e recupero dopo occlusione. Soglie di accettazione da concordare, non già raggiunte. 3. Provare tiri veloci, rimbalzi, mani sul disco, battitori dello stesso colore e distrazioni ai bordi; verificare che le tracce incerte siano riconoscibili. 4. Misurare separatamente cattura, analisi, generazione dati ed esportazione. Annotare CPU, memoria, temperatura, backlog e tempo dal gol al replay disponibile. 5. Controllare overlay durante pausa, seek, velocità 1×/½/¼ e ridimensionamento. Verificare che il rallentamento non divida per quattro la velocità fisica indicata. 6. Eseguire salvataggi ripetuti con partita, streaming e AI attivi; provare disconnessioni e carichi elevati. Il conteggio dei gol e i comandi devono continuare. 7. Verificare il file esportato anche su un altro dispositivo e mantenere originale, dati e calibrazione. Non sono stati acquistati acceleratori o scelti modelli, protocolli AI, dataset o soglie di accuratezza. Aggiornare CAD, schema e distinta solo dopo la scelta dell’hardware, senza attribuire questa pipeline al firmware attuale delle ESP32. ## Fonti primarie consultate nella discussione - [OpenCV: soglie HSV / inRange](https://docs.opencv.org/4.x/da/d97/tutorial_threshold_inRange.html). - [OpenCV: caratteristiche dei contorni](https://docs.opencv.org/4.x/dd/d49/tutorial_py_contour_features.html). - [OpenCV: calibrazione camera](https://docs.opencv.org/4.x/dc/dbb/tutorial_py_calibration.html). - [OpenCV: filtro di Kalman](https://docs.opencv.org/4.x/dd/d6a/classcv_1_1KalmanFilter.html). - [GStreamer: cairooverlay, disegno e timestamp](https://gstreamer.freedesktop.org/documentation/cairo/index.html). - [Raspberry Pi: software AI](https://www.raspberrypi.com/documentation/computers/ai.html). - [Raspberry Pi: AI HATs](https://www.raspberrypi.com/documentation/accessories/ai-hat-plus.html). - [Raspberry Pi: software camera e frame rate](https://www.raspberrypi.com/documentation/computers/camera_software.html). I componenti citati esistono; la loro disponibilità non dimostra che l’applicazione completa sia già implementata o soddisfi le prestazioni desiderate. Le scelte sopra sono una proposta da collaudare sul nostro tavolo. ## Display sul supporto camera — richiesta del 17 ottobre 2026 L’utente richiede un display **a colori da 10 oppure 13 pollici**, sul supporto della telecamera nella parte frontale, alimentato/gestito dal Raspberry per vedere replay con traiettorie sovrapposte. Richiesti anche layout grafico ed esempio animato 3D. Funzione richiesta confermata; diagonale definitiva, modello commerciale, fissaggio, alimentazione e implementazione restano aperti. L’esempio dovrà distinguere chiaramente animazione simulata e tracking di immagini reali. Proposta da revisionare: pannello 10,1″ orizzontale, rivolto verso il lato lungo frontale del tavolo, con alternativa 13,3″ nello stesso confronto. Area attiva ideale 16:9 circa 224 × 126 mm oppure 294 × 166 mm, calcolata dalla diagonale: non quote dell’involucro o di un prodotto scelto. Posizionamento sulla faccia anteriore del montante, sotto il braccio, arretrato rispetto alla camera per non entrare nel suo cono ottico. Il centro e i limiti esatti si definiscono sul CAD controllando ingombri, visibilità dal tavolo e fascio ottico; nessuna quota di montaggio ancora confermata. Collegamento proposto: HDMI per il video; alimentazione secondo il display scelto, con linea dimensionata. USB opzionale per touch, non richiesto dall’utente. Non presumere che una porta Raspberry basti ad alimentare qualsiasi pannello. Peso, momento sul montante, staffe e stabilità da verificare: il 13,3″ può richiedere rinforzi. Layout proposto: fondo grafite, azzurro e corallo per i giocatori; fascia alta con nomi/punteggio e stato “REPLAY”; vista del campo centrale dominante con scia e marcatori dei rimbalzi; fascia inferiore con avanzamento, pausa e velocità 1× / ½ / ¼, attivazione traiettoria. Traccia continua per osservazioni, tratteggiata per previsioni, interrotta se persa. Le statistiche simulate si indicano come dimostrative. Esempio richiesto: scena 3D del tavolo con montante, camera e schermo, confronto 10,1″/13,3″, vista frontale e ravvicinata dello schermo, azione e replay rallentato con traiettoria progressiva sincronizzata. Il display non deve mostrare un’inquadratura che include ricorsivamente se stesso. Base: CAD e animazione del tavolo già esistenti; nessuna modifica al plastico ferroviario. Stato al 17 ottobre, dopo approvazione: creati [CAD10,1″](STEP/airhockey_display.step), [CAD13,3″](STEP/airhockey_display13.step) e [layout con animazione3D](replay-display.html). I due GLB derivano dai rispettivi STEP; stessa scena CAD per tavolo e ripresa dall’alto, con piano display escluso dalla ripresa per evitare ricorsione. Disco e battitori animati; scia e indicazione di rimbalzo sincronizzate a un unico tempo, inclusi seek, pausa, velocità e ritorno a inizio clip. La modalità partita→replay simula il gol, aggiorna il punteggio e avvia il rallentatore. La traiettoria dimostrativa è interamente sintetica, non contiene misure o previsioni prodotte da visione reale. Controlli geometrici:346 solidi validi e positivi per variante; carcassa fuori dal cono utile del campo800×400, margine laterale conservativo162,7mm per10,1″ e156mm per13,3″. Questo non certifica carichi o attacchi del prodotto reale. Nessuna acquisizione, tracking su filmati o misura sul Raspberry ancora implementata.