Configurare e regolare il sonar
Scegli il backend di calcolo, poi confronta copertura, dettaglio e frequenza di aggiornamento. Il riferimento del sonar multibeam contiene avvio rapido, SDF e parametri.
Scegliere l'ambiente
Usa i terminali POSIM preparati. Modifica, compila ed esegui nella stessa installazione Ubuntu, WSL o Docker; POSIM_WS ne indica lo spazio di lavoro. Tutti i backend richiedono i sensori di rendering di Gazebo.
| Ambiente | Opzioni |
|---|---|
| Linux nativo | CPU; WGPU con un adattatore Vulkan utilizzabile; CUDA con GPU NVIDIA e toolkit compatibili |
| WSL 2 o container Linux | CPU; per il calcolo GPU, adattatore e driver devono essere accessibili dentro l'ambiente |
| Docker/RDP su macOS | Inizia con CPU. Il container Linux non espone il dispositivo Metal del Mac. |
| macOS nativo | WGPU può usare Metal con una toolchain ROS/Gazebo nativa preparata a parte; la guida macOS descrive Docker/RDP. |
auto prova CUDA → WGPU → CPU. Per confronti controllati, seleziona esplicitamente cpu, wgpu o cuda. Se il backend scelto non è disponibile, il sensore non si inizializza. Consulta la tabella delle opzioni.
Compilare i pacchetti del sonar
Parti dall'installazione dai sorgenti con le dipendenze già installate. wgpu_vendor compila la libreria Rust anche per usare CPU. Verifica Rust e Cargo; se mancano, segui l'installazione ufficiale.
rustc --version
cargo --version
Dallo spazio di lavoro con l'ambiente caricato, compila libreria, sensore, sistema del mondo ed esempio:
cd "$POSIM_WS"
colcon build --merge-install --executor sequential --symlink-install \
--packages-up-to multibeam_sonar_system posim_multibeam_sonar_demo
source install/setup.bash
CUDA è facoltativo. Per ignorare un toolkit installato e compilare CPU/WGPU, aggiungi --cmake-args -DCMAKE_DISABLE_FIND_PACKAGE_CUDAToolkit=ON. Cargo.lock fissa le dipendenze Rust; il primo download richiede Internet.
ros2 pkg prefix wgpu_vendor
ros2 pkg prefix multibeam_sonar
ros2 pkg prefix multibeam_sonar_system
ros2 pkg prefix posim_multibeam_sonar_demo
Controlla tutti e quattro i pacchetti, poi esegui l'esempio e ricevi immagini e dati grezzi. La presenza di un pacchetto non conferma che il sensore si carichi. Verifica i pacchetti dentro il container; se mancano, compila i sorgenti senza presumere che un tag dell'immagine li includa.
Scegliere l'adattatore WGPU
Su Linux, esegui vulkaninfo --summary nell'ambiente di Gazebo, con driver e strumenti Vulkan del sistema. Un adattatore software come llvmpipe può eseguire Vulkan senza accelerazione hardware. WGPU mostra all'avvio l'adattatore selezionato.
WGPU_BACKEND=vulkan \
ros2 launch posim_multibeam_sonar_demo multibeam_sonar_demo.launch.py \
compute_backend:=wgpu
| Variabile | Uso |
|---|---|
WGPU_BACKEND |
vulkan su Linux, metal in un processo macOS nativo; omettila per le impostazioni della piattaforma |
WGPU_ADAPTER_NAME |
Primo adattatore il cui nome contiene il testo, senza distinguere maiuscole; usa un nome mostrato dal driver o all'avvio |
WGPU_POWER_PREF |
high, low o none; predefinito high quando non è indicato un nome |
Imposta le variabili prima dell'avvio. Dopo averle cambiate, arresta e rilancia la simulazione: l'inizializzazione è condivisa nel processo. Il progetto wgpu descrive le API. Se l'inizializzazione o il controllo delle risorse falliscono, esamina adattatore e limiti, poi scegli cpu o riduci le dimensioni del sensore.
Configurare CUDA, se necessario
Servono driver NVIDIA, compilatore/runtime CUDA, cuFFT e cuBLAS. Verifica l'ambiente di esecuzione:
nvidia-smi
nvcc --version
Per i container Linux configura NVIDIA Container Toolkit sull'host. Su Windows segui CUDA su WSL e, se necessario, la configurazione GPU di Docker Desktop. Installa il driver video Windows, non un driver Linux dentro WSL. Anche il container deve avere le librerie CUDA.
Scegli un'architettura compatibile. L'esempio usa SM 75: sostituisci 75 con il valore della tua GPU. OFF riattiva la ricerca del toolkit dopo una compilazione solo CPU/WGPU.
colcon build --merge-install --executor sequential --symlink-install \
--packages-up-to multibeam_sonar_system posim_multibeam_sonar_demo \
--cmake-args -DCMAKE_DISABLE_FIND_PACKAGE_CUDAToolkit=OFF \
-DCMAKE_CUDA_ARCHITECTURES=75
source install/setup.bash
nvcc --list-gpu-code elenca i target disponibili. Senza scelta esplicita vale il valore predefinito del compilatore. Con più toolkit, usa -DCUDAToolkit_ROOT=/path/to/cuda e aggiungi il relativo bin a PATH. Avvia l'esempio con compute_backend:=cuda.
Misurare un riferimento
Mantieni fissi scena, distanza dal bersaglio e posa del sensore. Nel terminale B:
ros2 topic hz /sensor/multibeam_sonar/sonar_image
Interrompi con Ctrl+C, poi controlla la velocità della simulazione:
gz topic -e -t /world/default/stats
L'entità del mondo si chiama default. Registra real_time_factor insieme alla frequenza ricevuta: richiedere 30 Hz nel tempo simulato non garantisce 30 immagini al secondo reale. Esci con Ctrl+C.
Regolare campionamento e portata
Modifica un valore alla volta in una copia del SDF, ricompila, carica l'ambiente e avvia con la stessa posa.
| Esperimento | Confronto | Cosa osservare |
|---|---|---|
| Dettaglio angolare | 512 contro 256 fasci orizzontali, stesso campo visivo | Separazione dei bersagli e frequenza |
| Campionamento verticale | 300 contro 150 raggi | Continuità dei bersagli e tempo di calcolo |
| Copertura | Cambiare insieme portata dei raggi e maxDistance |
Bersaglio più lontano e scala delle distanze |
| Aggiornamento | 30 contro 10 Hz | Frequenza ricevuta e fattore di tempo reale |
| Salto dei raggi | raySkips 10 contro 5 |
Dettaglio verticale e costo di calcolo |
Il passo in distanza è soundSpeed / (2 × bandwidth); la griglia ha ceil(maxDistance / passo) + 1 celle. Con 1500 m/s, 29.9 kHz e 15 m sono 599. L'ultima coordinata può superare leggermente maxDistance, ma gli echi oltre portata vengono esclusi. Leggi distanze e numero di fasci dal messaggio grezzo o dal CSV.
WGPU conserva la lunghezza richiesta, anche se non è una potenza di due, e sceglie automaticamente gli stadi FFT. Portata e larghezza di banda maggiori aumentano memoria e lavoro. Nella modalità a griglia predefinita, CPU assegna gli echi alla cella di distanza più vicina; GPU elabora nel dominio delle frequenze. Confronta anche ampiezza e risposta in distanza tra backend.
Conservare un confronto riproducibile
Attendi che il rendering si stabilizzi. Disattiva writeLog e debugFlag per misurare il throughput; registra separatamente con CSV o ROS. blazingSonarImage=false fissa il seme a 1234.
Salva SDF, revisione POSIM, backend/adattatore, versioni driver/toolkit, tempo per immagine, frequenza ricevuta, fattore di tempo reale e memoria. Confronta dati grezzi di intensità/distanza oltre alle schermate. Le citazioni riportano il modello scientifico.
Elaborazione GPU

Le fasi comprendono somma dei raggi, correzione dei fasci e FFT. WGPU applica anche la finestra in frequenza fornita; il percorso CUDA non la applica. Misura separatamente calcolo e trasferimenti di memoria. Figura: POSIM Notion Wiki.
Con l’SDK macOS di Gazebo Sim 10.5 testato, i mondi in cui il sonar è l’unico sensore possono arrestarsi durante l’inizializzazione di Ogre2. Se usi questo SDK, aggiungi al mondo una piccola telecamera integrata.
Trasporto ROS su macOS nativo
Con Fast DDS su macOS nativo, usa il profilo locale installato se non arrivano i messaggi sonar di grandi dimensioni con QoS best-effort. Il profilo prevede un segmento di memoria condivisa da 16 MiB e buffer dei messaggi di trasporto da 1 MiB. UDP su localhost usa datagrammi da 8192 byte e buffer dei socket di invio e ricezione da 2 MiB ciascuno. Imposta la variabile in ogni terminale del simulatore, del bridge e del sottoscrittore prima di avviare i processi:
export FASTDDS_DEFAULT_PROFILES_FILE="$(ros2 pkg prefix multibeam_sonar)/share/multibeam_sonar/config/fastdds_macos_local.xml"
Il profilo è facoltativo ed è limitato ai processi sullo stesso Mac. Per comunicare con altri computer, usa un profilo di rete adeguato. Se FASTDDS_DEFAULT_PROFILES_FILE è già impostata, integra le impostazioni della memoria condivisa in quel profilo. Queste impostazioni di trasporto ROS si applicano sia al sonar CPU sia al sonar WGPU.