Ottimizzare tempi e memoria di WebODM: cosa incide davvero

Un'elaborazione che dura tutta la notte, o che si ferma con "out of memory" dopo tre ore, di solito non ha bisogno di un computer nuovo. Ha bisogno di scelte più consapevoli su cinque o sei parametri. In questa guida vedi cosa pesa davvero sul tempo e sulla memoria di WebODM, in ordine di importanza, e come intervenire senza rovinare il risultato.

1. Cosa incide davvero, in ordine#

Le ultime righe della tabella sono quelle su cui molti intervengono per prime, comprando hardware. Le prime sono quelle che cambiano il risultato.

2. Numero di immagini#

È il fattore dominante. Il matching cresce più che linearmente con il numero di foto e la memoria richiesta, secondo la documentazione di WebODM, passa da circa 16 GB per 250 immagini a 32 GB per 500 e 64 GB per 1.500 (vedi requisiti hardware).

Cosa puoi fare:

• In volo: non esagerare con la sovrapposizione. 75 % longitudinale e 65 % trasversale bastano per la maggior parte dei rilievi; 85/85 produce il doppio delle foto per un guadagno marginale (vedi acquisire le immagini).
• Prima del caricamento: elimina foto di decollo e atterraggio, foto sfocate, doppie, fuori area. Dieci minuti di pulizia risparmiano ore.
• Oltre 1.000–1.500 immagini: usa lo split-merge, spiegato nella guida ai dataset grandi.

3. Risoluzione delle immagini: "Resize images"#

Nel pannello di caricamento di WebODM trovi l'opzione "Resize images" (ridimensiona immagini), con un valore in pixel per il lato lungo (per esempio 2.048). Le immagini vengono ridotte nel browser prima dell'invio al nodo: risparmi tempo di caricamento, spazio e soprattutto memoria in ogni fase successiva.

Cosa perdi: risoluzione. Un'immagine da 5.472 px di lato ridotta a 2.048 ha un GSD effettivo circa 2,7 volte più grande: se hai volato a 2 cm/px, il tuo dataset ridotto vale circa 5 cm/px. Ortofoto e DEM non potranno essere più fini di così.

Quando usarlo:

• prove rapide per verificare che il dataset si ricostruisca, prima dell'elaborazione definitiva;
• progetti in cui la risoluzione richiesta è comunque inferiore a quella del volo (ortofoto d'insieme, NDVI, controllo cantiere);
• macchine con 8–16 GB di RAM che altrimenti non arriverebbero in fondo.

Quando non usarlo: rilievi in cui il GSD è il requisito (topografia, misure di dettaglio, beni culturali).

Il ridimensionamento non è reversibile sul nodo: se cambi idea devi caricare di nuovo le immagini originali.

4. Le due opzioni "quality"#

4.1 --feature-quality (default high)#

Governa la risoluzione a cui vengono cercate le feature nella prima fase. Da high a medium la fase di estrazione e matching diventa nettamente più veloce e leggera, con un impatto limitato sulla qualità finale nella maggior parte dei dataset con buona texture. ultra costa molto e serve solo con superfici difficili (vegetazione, neve, sabbia: vedi casi particolari).

4.2 --pc-quality (default medium)#

È il parametro più costoso della pipeline dopo il numero di immagini. Determina la risoluzione delle mappe di profondità e quindi la densità della nuvola. Il salto da medium a high moltiplica tempo e memoria della fase di densificazione; ultra lo fa di nuovo.

Regola pratica:

5. Saltare quello che non ti serve#

--fast-orthophoto merita una nota: è il modo più rapido per ottenere un'ortofoto, ma la geometria viene dalla nuvola sparsa, quindi edifici, alberi e scarpate producono deformazioni visibili. Per un campo agricolo o un piazzale va benissimo; per un centro storico no. Il preset "Fast Orthophoto" di WebODM la attiva insieme a --skip-3dmodel.

6. Mesh, DEM e ortofoto: risoluzioni realistiche#

• --mesh-octree-depth oltre 12 e --mesh-size oltre il milione di vertici alzano molto la memoria della fase di meshing. Servono per modelli 3D di dettaglio, non per ortofoto.
• --dem-resolution e --orthophoto-resolution più fini del GSD non aggiungono informazione, ma moltiplicano i pixel da scrivere. Il motore le limita al GSD realistico; non aggirare il limite con --ignore-gsd.
• --dem-gapfill-steps alto e --dtm aggiungono tempo alla fase DEM, di solito accettabile.

7. Parallelismo: --max-concurrency#

Imposta quanti processi paralleli usa il motore. Più thread significa più velocità nelle fasi parallelizzabili, ma anche più memoria di picco: ogni thread lavora su una porzione di dati propria.

• Se vai in out of memory, abbassa --max-concurrency (per esempio da 8 a 4): l'elaborazione rallenta ma finisce.
• Su macchine con molti core e molta RAM, alzalo fino al numero di core fisici.
• Non alzarlo oltre i core disponibili: non guadagni nulla.

Il default riportato nella documentazione dipende dalla macchina; verifica il valore nel pannello opzioni di WebODM o con --help.

8. Disco: SSD contro HDD#

La fase di nuvola densa e quella di texturizzazione leggono e scrivono decine di GB di file temporanei. Su un disco meccanico questo diventa il collo di bottiglia: la CPU aspetta il disco.

• Metti la cartella del nodo di elaborazione su un SSD (--node-dir in webodm.sh; vedi installazione su Linux).
• Su Windows e macOS con Docker Desktop, controlla che il disco virtuale di Docker sia su SSD e abbastanza grande (default 20 GB, da aumentare).
• Con --optimize-disk-space riduci l'occupazione, non la velocità.

9. GPU: cosa accelera davvero#

Una GPU NVIDIA con CUDA accelera solo l'estrazione delle feature, su Linux o WSL2, quando WebODM è avviato con --gpu. Su un dataset tipico questa fase è una frazione del tempo totale: il guadagno complessivo è reale ma limitato, e nullo sulla nuvola densa, sulla mesh e sull'ortofoto. La documentazione di ODM è ancora più netta e dichiara che la GPU "non offre attualmente vantaggi di prestazioni" nella sua distribuzione.

ODX ha annunciato il supporto alle GPU RTX serie 50 e lavora sull'accelerazione di altre fasi: per lo stato attuale consulta docs.webodm.org. Configurazione e verifica nella guida alla GPU NVIDIA.

Se devi scegliere dove spendere: prima RAM, poi SSD, poi CPU con più core, per ultima la GPU.

10. RAM assegnata a Docker#

Su Windows e macOS, WebODM in Docker può usare solo la memoria che Docker Desktop gli concede, non tutta quella del computer. Il default è spesso di pochi GB. Vai in Settings → Resources e assegna almeno 4 GB, meglio 16 GB o più se il computer li ha. L'errore "out of memory" con un PC da 32 GB è quasi sempre questo. Su Linux con Docker Engine il limite non esiste.

Gli installer nativi di WebODM per Windows e macOS non passano da Docker e usano la memoria di sistema direttamente.

11. Un metodo di lavoro#

1. Prova veloce: immagini ridimensionate a 2.048 px, preset "Fast Orthophoto" oppure --end-with opensfm. Verifichi in poco tempo che il dataset si ricostruisca e che le foto siano tutte usate.
2. Elaborazione definitiva con immagini originali e le sole opzioni che servono al prodotto richiesto: --skip-3dmodel se non ti serve il 3D, --pc-quality adeguato, --dsm/--dtm se servono.
3. Se fallisce per memoria: abbassa --max-concurrency, poi --pc-quality, poi --feature-quality; se ancora non basta, ridimensiona o passa allo split.
4. Salva la combinazione come preset in WebODM, così la riusi su progetti simili.

Problemi frequenti#

Out of memory a metà elaborazione. Nell'ordine: RAM di Docker Desktop troppo bassa; --max-concurrency troppo alto; --pc-quality alto; troppe immagini per la RAM disponibile. Vedi anche errori comuni.

Il computer è potente ma WebODM è lento lo stesso. Disco meccanico, oppure Docker Desktop con pochi core e poca RAM assegnati, oppure antivirus che analizza i file temporanei (su Windows, escludi la cartella dei dati di WebODM).

Ho ridimensionato le immagini e l'ortofoto è "sgranata". È l'effetto atteso: il GSD effettivo è aumentato. Ricarica le immagini originali per l'elaborazione definitiva.

La GPU non viene usata. Verifica driver, NVIDIA Container Toolkit e avvio con --gpu; ricorda che accelera solo l'estrazione delle feature, quindi il resto dell'elaborazione non cambia. Vedi GPU NVIDIA.

Prossimi passi#

• Requisiti hardware: la tabella immagini/RAM e configurazioni di esempio.
• Dataset grandi: split e merge: quando il ridimensionamento non basta.
• Riferimento completo delle opzioni: default e significato di ogni parametro citato qui.