Dataset grandi in WebODM: split, merge e ClusterODX

Fino a qualche centinaio di immagini WebODM lavora senza sorprese. Oltre le 1.000–1.500 immagini entri in un altro regime: la memoria necessaria cresce in fretta, i tempi si misurano in ore o giorni e un errore a metà strada costa molto. Il motore ha una modalità pensata proprio per questo, chiamata split-merge: divide il dataset in sottomodelli, li elabora uno alla volta (o in parallelo su più macchine) e riunisce i risultati. In questa guida vedi come usarla e cosa aspettarti.

1. Quando un dataset è "grande"#

Il fattore limitante è quasi sempre la RAM. La documentazione di WebODM indica, come ordine di grandezza, le seguenti corrispondenze per un'elaborazione senza split:

Sono valori per immagini di risoluzione tipica (20 megapixel circa) con qualità predefinite. Con --pc-quality high o --feature-quality ultra il fabbisogno sale ancora.

Lo split serve quindi in due casi:

1. Il dataset supera le 1.000–1.500 immagini. Anche con una macchina ben dotata, oltre questa soglia la ricostruzione SfM in un unico blocco diventa lenta e fragile: un'immagine problematica può far fallire tutto dopo molte ore.
2. La RAM non basta per il dataset che hai, qualunque sia la sua dimensione. Con 16 GB e 600 immagini, per esempio, dividere in due o tre sottomodelli permette di completare il lavoro.

Prima di dividere, chiediti se puoi ridurre il dataset: eliminare foto di decollo e atterraggio, foto doppie, strisciate fuori area. Il pannello di caricamento di WebODM offre anche il ridimensionamento delle immagini, che riduce il fabbisogno di memoria a costo di risoluzione (vedi ottimizzare tempi e memoria).

2. Come funziona split-merge#

Il flusso, in sintesi:

1. Ricostruzione sparsa globale. Il motore estrae le feature da tutte le immagini e fa il matching. Questa fase non viene divisa e resta la più pesante in memoria per dataset molto grandi.
2. Divisione in sottomodelli. Le immagini vengono raggruppate per vicinanza spaziale (in base alle posizioni GPS) in gruppi di circa --split immagini, con una fascia di sovrapposizione di --split-overlap metri tra gruppi adiacenti.
3. Elaborazione di ogni sottomodello. SfM, nuvola densa, mesh, DEM e ortofoto vengono calcolati separatamente per ogni gruppo, in sequenza sulla stessa macchina oppure in parallelo su un cluster.
4. Allineamento. I sottomodelli vengono allineati tra loro usando la sovrapposizione (e i GCP, se presenti).
5. Merge. Nuvole di punti, DEM e ortofoto vengono uniti in prodotti unici. Le ortofoto sono fuse lungo linee di taglio (cutline) calcolate automaticamente.

Il modello 3D texturizzato non viene unito: se ti serve una mesh unica dell'intera area, lo split non è la strada. Per dataset grandi, del resto, la mesh completa è raramente il prodotto richiesto.

3. Le opzioni#

3.1 Scegliere --split#

Il valore giusto dipende dalla RAM: ogni sottomodello deve stare comodamente in memoria da solo. Come punto di partenza, usa la tabella del §1 al contrario: con 32 GB, sottomodelli di 400–500 immagini; con 64 GB, 800–1.000. Se un sottomodello va in out of memory, abbassa il valore e rilancia.

Sottomodelli troppo piccoli (meno di 200 immagini) hanno più bordi, quindi più zone di sovrapposizione da allineare e più possibilità di piccole discontinuità nel merge.

3.2 Scegliere --split-overlap#

La sovrapposizione di 150 m è un default ragionevole per voli a 80–120 m di quota. La fascia deve contenere abbastanza immagini in comune perché l'allineamento sia stabile:

• alza il valore (200–250 m) su voli ad alta quota, su terreni con poca texture o se noti gradini nel DEM ai confini tra sottomodelli;
• abbassa il valore (100 m) su voli bassi e densi per ridurre il lavoro doppio.

3.3 --split-image-groups#

Quando il volo è stato fatto in più sessioni o in più zone separate, lasciar decidere al motore può produrre gruppi che tagliano una zona a metà. Con un file di testo indichi tu la divisione: una riga per immagine, con nome del file e nome del gruppo separati da uno spazio.

DJI_0001.JPG zonaA
DJI_0002.JPG zonaA
...
DJI_0891.JPG zonaB
DJI_0892.JPG zonaB

Il file si carica insieme alle immagini. Le fasce di sovrapposizione vengono comunque gestite con --split-overlap.

3.4 --merge#

Con --merge orthophoto o --merge dem chiedi al motore di unire solo il prodotto che ti serve. Su dataset molto grandi l'unione della nuvola di punti (pointcloud) è la fase più lunga e produce file di decine di GB: se non ti serve la nuvola intera, escludila.

4. GCP e georeferenziazione con lo split#

I GCP funzionano anche in modalità split: il motore assegna ogni punto ai sottomodelli che contengono le sue immagini. Per un buon risultato, distribuisci i GCP in modo che ogni sottomodello ne contenga almeno tre, meglio se alcuni cadono nelle fasce di sovrapposizione: aiutano l'allineamento. Con un drone RTK e --gps-accuracy corretto l'allineamento tra sottomodelli è più semplice, perché le posizioni delle camere sono già coerenti. Riferimenti nelle guide su GCP e RTK/PPK.

5. Un solo computer o un cluster#

5.1 Sulla stessa macchina#

Senza --sm-cluster, i sottomodelli vengono elaborati in sequenza sul nodo che ha ricevuto il task. Il vantaggio è solo di memoria: il tempo totale è simile, o leggermente superiore, a quello di un'elaborazione unica che riuscisse a completarsi. È il caso più comune: una workstation con 32–64 GB che deve digerire 2.000–4.000 immagini.

5.2 Con ClusterODX/ClusterODM#

ClusterODX (WebODM) e ClusterODM (OpenDroneMap) sono bilanciatori che ricevono i task e li distribuiscono su più nodi di elaborazione (NodeODX/NodeODM). Con --sm-cluster http://indirizzo-del-cluster:3000 il motore invia ogni sottomodello a un nodo diverso e li elabora in parallelo, poi raccoglie i risultati per il merge.

Serve:

• più macchine (fisiche, virtuali o istanze cloud) con NodeODX/NodeODM installato;
• una macchina con ClusterODX/ClusterODM che le conosca;
• che il nodo principale possa raggiungere il cluster via rete.

In WebODM colleghi il cluster come un normale nodo di elaborazione. La configurazione è spiegata nella guida a NodeODM e ClusterODM. Quale dei due usare dipende dalla distribuzione: con WebODM e ODX usa ClusterODX; con l'ecosistema OpenDroneMap usa ClusterODM. Alla data di verifica i due progetti condividono l'architettura, ma divergono: controlla la compatibilità con la tua versione nella documentazione ufficiale.

Con il cluster il tempo totale scende quasi in proporzione al numero di nodi, tranne le fasi non divisibili (matching iniziale e merge).

6. Spazio disco e --optimize-disk-space#

Un dataset grande produce file intermedi enormi: mappe di profondità, nuvole per sottomodello, mesh, texture. Per 3.000 immagini puoi facilmente superare i 200–300 GB temporanei.

--optimize-disk-space elimina i file intermedi appena non servono più. Costo: non puoi più usare "Riavvia da" una fase (--rerun-from), perché i dati da cui ripartire sono stati cancellati. Su dataset grandi il compromesso è quasi sempre accettabile: meglio finire che poter rilanciare.

Altri accorgimenti:

• usa un SSD per la cartella del nodo (--node-dir in webodm.sh, vedi installazione Linux): la fase di nuvola densa legge e scrive continuamente;
• verifica il disco assegnato a Docker su Windows e macOS (default 20 GB, del tutto insufficiente);
• scarica e archivia i risultati appena il task finisce, poi libera il nodo.

7. Tempi realistici#

I tempi dipendono da CPU, RAM, disco, qualità scelta e dal dataset stesso. Non diamo numeri precisi perché sarebbero falsi per la tua macchina; gli ordini di grandezza, con opzioni predefinite, sono questi:

Tre cose allungano i tempi più di ogni altra: --pc-quality alto, immagini a piena risoluzione da sensori oltre 40 megapixel, e un disco meccanico. Tre cose li riducono: --skip-3dmodel, --fast-orthophoto (se accetti i suoi limiti) e la GPU per l'estrazione delle feature. Approfondimento nella guida a tempi e memoria.

Se il tempo è il vincolo principale, la strada più semplice è affittare per un giorno un'istanza cloud con molta RAM e usarla come nodo di elaborazione remoto: la guida al server cloud spiega come.

Problemi frequenti#

Out of memory anche con lo split. La fase iniziale di matching non viene divisa. Riduci --feature-quality a medium, ridimensiona le immagini al caricamento, oppure abbassa --split. Se il problema è in un sottomodello, abbassa ancora --split.

Gradini o disallineamenti tra sottomodelli. Poca sovrapposizione: alza --split-overlap. Verifica anche che ogni sottomodello abbia GCP a sufficienza, se li usi.

Un sottomodello fallisce e il task si ferma dopo ore. Controlla la console per capire quale gruppo e perché (spesso poche feature o immagini corrotte). Rimuovi le immagini problematiche o usa --split-image-groups per controllare la divisione. Senza --optimize-disk-space puoi ripartire dalla fase fallita.

"No space left on device". Attiva --optimize-disk-space, aumenta il disco di Docker, sposta --node-dir su un disco più grande. Vedi errori comuni.

Il modello 3D è incompleto. È atteso: con lo split la mesh texturizzata non viene unita. Se ti serve, elabora un sottoinsieme di immagini senza split.

Prossimi passi#

• Ottimizzare tempi e memoria: cosa incide davvero sulle risorse, con o senza split.
• NodeODM e ClusterODM: mettere in piedi il cluster.
• WebODM su server cloud: affittare RAM a ore per il singolo dataset grande.