CONSIGLIO, ANZI, COSTRINGO CHIUNQUE ABBIA INTENZIONE DI METTERE MANO AL PROGETTO DI LEGGERE QUESTO FILE. SENZA DI QUESTO SARà CERTAMENTE POSSIBILE INTERPRETARE GLI SCRIPT E I MODELLI SIMULINK, MA MODIFICARLI SARà UN INFERNO.
Per qualsiasi dubbio, contattatemi pure a renycerrato@gmail.com e sarò felice di aiutarvi.

# Swarm UGV off-road — Phase 4/5 (MATLAB/Simulink)

Ciao! Se stai leggendo questo file probabilmente sei il prossimo tesista e devi portare avanti questo lavoro. Qui trovi tutto quello che serve per far girare la simulazione dello sciame di 3 veicoli off-road: planner A*, leader–follower, modello veicolo 8 DOF, MPC, mappa scoperta progressivamente. Buona fortuna!

## Come si lancia (basta la demo)

**Apri MATLAB in questa cartella e lancia `demo_swarm_phase4.m`. Fine.** Non devi caricare niente prima: i Bus di Simulink, l'MPC, la mappa motore, lo scenario, i model workspace... viene tutto creato dentro la demo stessa, che chiama le relative funzioni in ordine. Nessun requisito, nessun setup manuale.

Due alternative/scorciatoie:

- la demo è già stata runnata sulla mappa presentata in tesi: se vuoi solo guardare i risultati senza aspettare la simulazione, carica il workspace `SOLUZIONE.mat` e lancia direttamente le funzioni di plot/replay, scrivendo nel command window
visualize_terrain_map(map, scenario);
visualize_swarm_phase4(map_final, scenario, t_log, x, y, psi, v, alpha, delta, pct_known_log, wheelLog);
plot_swarm_signals(plotGlobal, scenario);
plot_mu_compaction(map_final, scenario);
- dopo che hai lanciato la demo le prime volte, puoi commentare le righe che ricaricano motore, MPC, Buses eccetera, così la alleggerisci. **Però lascia sempre `clear functions`**: serve a pulire le variabili `persistent` dentro le funzioni (isteresi del ranking, guardia anti-U-turn, evento mappa...), che altrimenti restano in memoria nonostante il `clear` e ti falsano la run successiva.

## Cambiare la simulazione

- **Mappa**: metti nella stessa cartella delal demo un nuovo file chiamato `semantic_map.png` in questa cartella e rilancia. Tutto qui. Se vuoi generarne un altro sulla base di una foto satellitare in tuo possesso, continua a leggere, avanti dirò come fare.
- **Partenze e goal**: coordinate iniziali (x, y, psi) dei veicoli, coordinate del goal e tutti i parametri (anche quelli fisici del veicolo) stanno in `init_swarm_scenario.m`. Occhio che dentro trovi già i due casi usati in tesi (CASO 1 / CASO 2) commentati (% prima della riga).
- **Sciame più grande**: copia-incolla i blocchi Agent nel Simulink (`swarm_phase_5.slx`), aggiungi le coordinate di partenza in `scenario.start` e gli offset rispetto al leader in `scenario.formation.offsets_body`. I blocchi sono Model Reference quindi la struttura è identica per tutti, cambiano solo gli argomenti. I buses di simulink sono tutti creati dalla funzione function define_swarm_buses(N_VEH, L), che come vedi è già parametrizzata sul numero di veicoli.
- **Mappe più grandi**: `define_swarm_buses(N_VEH, 1000)` viene chiamata con lunghezza massima del vettore percorso = 1000, per limitare il calcolo. Se metti una mappa con distanze molto maggiori, alza pure questo numero anche di 100–1000 volte: è solo un limite massimo (ma non esagerare a vuoto, meglio tenere i vettori corti soprattutto in fasi preliminari, se c'è qualcosa che non va nel planner il tempo di calcolo aumenta tanto quanto questo numero).
- Se vuoi mettere mano al file Simulink, prima leggi la documentazione MATLAB su **Argument Variables**, **parent/child model workspace** e la definizione dei **Bus**, o quantomeno informati su internet guardando i video YouTube di MATLAB stesso inerenti a questi argomenti. Sono video molto brevi (2-3 minuti in tutto) ma ti semplificheranno MOLTO la vita. Mi dispiace, ma i buses mi sono stati necessari per raggruppare quanto più possibile i segnali, non potevo farne a meno.
**Mappa motore**: se in un'applicazione futura decidete di usare un motore diverso, dovrai di sicuro cambiare i file che generano le mappe motore, ma poi devi cambiare anche i parametri del motore utilizzati per il design dell'MPC e per il calcolo della coppia in flux weakening nella funzione in ingresso all'mp, quella collegata alla measured desturbance. poterbbero essere presenti anche altri parametri in giro nel Simulink, come i gain che trasformano la % acceleratore in Cm.

## La parte AI su Python per la creaione della mappa semantica è SEPARATA

Il riconoscimento AI delle immagini satellitari **non sta in questa cartella e non è collegato in automatico**: è un progetto Python a parte (cartella `AI TRAINING`). Il flusso è manuale:

1. serve almeno Python 3.14; lanci `predict.py`;
2. per cambiare l'immagine da convertire in semantic mask: Edit Configurations → Parameters, così: `--image "C:\tuo_percorso\AI TRAINING\inputs\immagine.png" --mode resized`; l'immagine può essere anche in altri formati, non per forza .png;
3. metti la foto in `AI TRAINING/inputs`; il risultato esce in `AI TRAINING/outputs/predictions`; se vuoi automatizzare ancora di più il processo puoi cambiare la cartella di output negli script, io ho deciso di tenerla separata così da poter decidere cosa dare in pasto a MATLAB;
4. **prendi l'immagine prodotta, rinominala `semantic_map.png` e trascinala a mano in questa cartella**. MATLAB non va a pescarla da solo, legge solo quello che trova qui.

Il modello è trainato sul [Semantic Drone Dataset della Graz University](https://ivc.tugraz.at/research-project/semantic-drone-dataset/), che non è studiato esattamente per questo tipo di foto, infatti non funziona benissimo; non è stato approfondito perché non era argomento di tesi, perché per le applicazioni future il riconoscimento avverrà, suppongo, con videocamere e altri sensori montati a bordo veicolo, e non dall'alto. Consiglio: fai più tentativi cambiando soprattutto le tonalità colore con un saftware tipo Lightroom o Photoshop - o anche attraverso l'AI - della foto satellitare di input. Io ho fatto direttamente generare un'immagine a ChatGPT per la seconda simulazione. Le immagini di Google Earth non hannno abbastanza dettaglio e quelle del dataset sono scattate a pochi metri dal suolo (troppo piccole). Trovare su internet un'immagine che va bene è più difficile di quanto sembri. In futuro magari anche altri dataset saranno sviluppati e disponibili per questo tipo di training, nel caso potete semplicemente inserire il nuovo dataset nella cartella AI TRAINING/training_set.

## Output e dove finiscono

- Il replay animato parte da solo a fine simulazione (`visualize_swarm_phase4.m`) e salva **snapshot ogni 5 s** (PNG + PDF) in `../Images/replay_snapshots/` — percorso relativo a questa cartella, se la sposti aggiornalo.
- Nella stessa funzione c'è il flag `make_video`: se è `true` esporta anche un **MP4** del pannello leader-path. Con `frame_dt = 0.1` il video è fluido; per un replay veloce di debug rimetti `frame_dt = 1` o anche più alto, e `pause_replay = 0.1`.
- I plot statici dei segnali (PDF per la tesi) li fanno `plot_swarm_signals.m` e `plot_mu_compaction.m`, sempre chiamati dalla demo.

## Cose utili da sapere prima di metterci mano

- L'albero completo delle chiamate (chi chiama chi, compresi i blocchi MATLAB Function dentro i modelli) è documentato nella tesi, sezione 3.5 "MATLAB Files". 
- `replan_steps` nel model workspace e `N_REPLAN` nel codice dello SwarmPlanner **devono coincidere**, idem `MAX_PATH_LEN` con la lunghezza usata in `define_swarm_buses`.
- In `init_swarm_scenario.m` ci sono ancora alcuni campi ereditati dalle fasi precedenti che non vengono più letti da nessuno (es. `v_leader_mps`, `k_heading`, `replan_period_s`...): non ti fidare del nome, verifica sempre chi li usa davvero.
- I guadagni PID assegnati nella demo (`Kp_h`, `Kp_v`, ...) sono superati dall'MPC ma il modello `vehicle.slx` li referenzia ancora in un blocco residuo: se li togli dalla demo senza togliere il blocco, la sim si rompe. Li ho lasciati perché quelli erano i valori ottimali per far funzionare il PID, che un domani si potrà sempre ricollegare.
- L'evento ostacolo a runtime (albero che cade a t = 15 s) sta in `MapEventInjector` dentro `swarm_phase_5.slx` e chiama `apply_map_event.m`: orario, forma e posizione dell'ellisse si cambiano lì.