ODM e ODX da riga di comando con Docker

WebODM e OpenDroneMap Desktop sono interfacce; il lavoro lo fa il motore. Puoi saltare l'interfaccia e parlare direttamente con il motore dal terminale: è ciò che fanno chi automatizza elaborazioni ricorrenti, chi lavora su server senza desktop e chi vuole controllare ogni singola opzione. In questa guida usi Docker per lanciare ODX (il motore della linea WebODM) o ODM (il motore della linea OpenDroneMap) su una cartella di immagini.

Una precisazione necessaria. Dal 6 aprile 2026 esistono due motori con la stessa origine: ODX, mantenuto da UAV4GEO per WebODM e distribuito come immagine webodm/odm, e ODM 3.6.0, mantenuto dalla nonprofit OpenDroneMap Inc. e distribuito come opendronemap/odm. Alla data della separazione erano identici; da allora divergono. La sintassi è la stessa, cambia il nome dell'immagine. Per il quadro completo vedi Ecosistema WebODM e OpenDroneMap nel 2026; per capire come individuare le differenze reali tra i due motori vedi Opzioni a confronto.

Quando preferire la riga di comando all'interfaccia#

La riga di comando non produce mappe navigabili né viste 3D nel browser: ottieni i file, che poi apri in QGIS, CloudCompare o in un'interfaccia. Se ti servono l'interfaccia e l'automazione insieme, la strada è un nodo di elaborazione con la sua API: vedi NodeODX/NodeODM, ClusterODX/ClusterODM e nodi di elaborazione.

Struttura delle cartelle#

Il motore si aspetta una cartella di lavoro che contiene una sottocartella per ogni progetto, e dentro ciascuna una cartella images con le foto. Per un progetto chiamato progetto:

/home/utente/datasets/
└── progetto/
    └── images/
        ├── DJI_0001.JPG
        ├── DJI_0002.JPG
        └── ...

Le immagini vanno in /home/utente/datasets/progetto/images. Se hai un file di punti di controllo a terra (GCP), mettilo nella cartella del progetto: il formato è descritto nella guida Punti di controllo GCP. Gli output verranno scritti in sottocartelle di progetto/, accanto a images.

Procedura#

1. Scaricare l'immagine Docker#

Scarica l'immagine del motore. Il nome dell'immagine è l'unica cosa che cambia tra le due linee; il download è di alcuni GB e va fatto una sola volta.

docker pull webodm/odm

docker pull opendronemap/odm

2. Lanciare l'elaborazione#

Il comando monta la cartella dei dataset dentro il container (opzione -v) e indica il nome del progetto da elaborare. --project-path /datasets dice al motore dove cercare la cartella progetto. La sintassi è identica nelle due linee.

docker run -ti --rm -v /home/utente/datasets:/datasets webodm/odm --project-path /datasets progetto

docker run -ti --rm -v /home/utente/datasets:/datasets opendronemap/odm --project-path /datasets progetto

Sostituisci /home/utente/datasets con il tuo percorso reale e progetto con il nome della cartella. Il terminale mostra il log dell'elaborazione fase per fase: lettura delle immagini, estrazione feature, matching, ricostruzione, nuvola densa, mesh, texture, georeferenziazione, DEM, ortofoto, report. Con --rm il container si autodistrugge alla fine, ma i risultati restano nella cartella montata.

Negli esempi che seguono usiamo una variabile di shell per il nome dell'immagine, così i comandi sono copiabili per entrambe le linee. Imposta la variabile una volta sola nel terminale:

IMG=webodm/odm          # linea WebODM / ODX
# oppure
IMG=opendronemap/odm    # linea OpenDroneMap / ODM

3. Aggiungere opzioni#

Le opzioni si aggiungono in coda al comando, dopo il nome dell'immagine. Sono le stesse che le interfacce mostrano nel pannello Opzioni; i nomi e i default sono in docs.webodm.org/options-flags per ODX e in docs.opendronemap.org/arguments per ODM. Al 6 aprile 2026 gli elenchi erano identici; per scoprire le differenze introdotte da allora esegui --help su ciascuna immagine, come spiegato in Opzioni a confronto. Un esempio che produce anche DSM e DTM, con ortofoto a 2 cm/px e nuvola in formato LAS:

docker run -ti --rm -v /home/utente/datasets:/datasets $IMG --project-path /datasets progetto --dsm --dtm --orthophoto-resolution 2 --pc-las

Le opzioni che userai più spesso da riga di comando:

Il riferimento completo, con consigli in italiano per ogni opzione, è nella Guida completa alle opzioni.

4. Trovare gli output#

Al termine, nella cartella progetto/ compaiono le sottocartelle dei risultati, ciascuna dedicata a un prodotto: ortofoto, modelli di elevazione (se richiesti), nuvola di punti georeferenziata, modello 3D con texture e report di qualità in PDF. I nomi esatti delle cartelle e dei file, con il dettaglio di ogni formato, sono nella pagina Outputs della documentazione OpenDroneMap per ODM e su docs.webodm.org per ODX: consultale prima di scrivere script che li leggono, perché alcuni file dipendono dalle opzioni scelte (per esempio dtm.tif esiste solo con --dtm) e perché i due motori potrebbero divergere nel tempo.

Le guide della sezione Output spiegano come usare ogni prodotto: Ortofoto, DSM, DTM e curve di livello, Nuvola di punti, Modello 3D.

Elaborare più progetti in batch#

Il vantaggio vero della riga di comando è la ripetibilità. Con una cartella per ogni progetto, un ciclo di shell li elabora uno dopo l'altro con le stesse opzioni. Questo esempio itera su tutte le sottocartelle di datasets e lancia il motore per ciascuna:

for p in /home/utente/datasets/*/; do
  nome=$(basename "$p")
  docker run -ti --rm -v /home/utente/datasets:/datasets $IMG --project-path /datasets "$nome" --dsm --dtm
done

Prima di lanciarlo su una notte intera, provalo su due progetti piccoli. Un batch su più progetti in parallelo raramente conviene: la RAM è il limite, e due elaborazioni contemporanee si contendono la stessa memoria. Meglio in sequenza.

Per riprendere un progetto interrotto senza ripartire da zero, --rerun-from accetta il nome della fase da cui ricominciare; --end-with ferma l'elaborazione a una fase precisa, utile per controllare la ricostruzione prima di investire ore nella nuvola densa. I nomi delle fasi sono nella documentazione delle opzioni.

Come verificare quale motore stai usando#

Con due immagini dalla sintassi identica è facile perdere traccia di quale motore ha prodotto un risultato. Prima di confrontare output o di scrivere una relazione tecnica, verifica il motore e la versione in tre modi.

1. Chiedi la versione al motore. L'opzione --version è nell'elenco degli argomenti di entrambi i motori. Sostituisci il nome dell'immagine con quella che vuoi controllare:

docker run --rm webodm/odm --version
docker run --rm opendronemap/odm --version

Annota la stringa restituita: indica il nome del motore e la versione così come li dichiara l'immagine.

2. Interroga l'immagine con Docker. docker inspect mostra il repository da cui proviene l'immagine, il digest e la data di creazione, indipendentemente da come il motore si presenta:

docker inspect webodm/odm --format '{{.RepoTags}} {{.Created}}'
docker inspect opendronemap/odm --format '{{.RepoTags}} {{.Created}}'

3. Confronta gli elenchi di opzioni. docker run --rm webodm/odm --help e docker run --rm opendronemap/odm --help elencano le opzioni di ciascun motore: le differenze, se ci sono, sono la traccia più concreta della divergenza. Il metodo completo è in Opzioni a confronto.

Nelle relazioni tecniche e nelle richieste di aiuto riporta sempre immagine, tag e output di --version: le due community rispondono su motori diversi.

Installazione nativa (senza Docker)#

Docker è la strada consigliata, ma il motore si installa anche in modo nativo. La procedura è documentata dalla linea OpenDroneMap; per ODX la scheda di riferimento di questo sito non riporta una procedura nativa verificata.

La procedura nativa è più fragile agli aggiornamenti di sistema e la consigliamo solo a chi ha una ragione precisa.

Problemi frequenti#

"Cannot process dataset" o poche feature. Il dataset ha problemi (sovrapposizione insufficiente, immagini sfocate, superfici uniformi). Controlla l'acquisizione con la guida Acquisire le immagini.

Il processo viene ucciso senza messaggio. Quasi sempre è la memoria: il sistema termina il container quando la RAM finisce. Riduci --pc-quality e --feature-quality, oppure ridimensiona le immagini, oppure usa una macchina più grande.

Permesso negato su Docker (Linux). Il tuo utente non è nel gruppo docker: sudo usermod -aG docker $USER, poi esci e rientra nella shell.

Il percorso con spazi non funziona. Racchiudi i percorsi tra virgolette e, su Windows/WSL2, usa i percorsi Linux (/mnt/c/...).

Il catalogo completo è nella guida Errori comuni.

Prossimi passi#

• Opzioni a confronto: come individuare con --help le differenze reali tra ODX e ODM.
• Guida completa alle opzioni: tutte le opzioni con default e consigli.
• Dataset grandi e split-merge: oltre 1.000 immagini con --split e --split-overlap.
• NodeODX/NodeODM, ClusterODX/ClusterODM e nodi di elaborazione: esporre il motore via API invece che da terminale.