Tutte le opzioni di WebODM e ODM: riferimento completo

Avanzato Entrambe le linee 25 min di lettura

Ultimo aggiornamento:

Testato con: ODM 3.6.0 / ODX (WebODM 3.x)

In questa pagina

Le opzioni di WebODM sono quelle del motore fotogrammetrico che gira sotto: ODX nelle installazioni WebODM, ODM nelle installazioni OpenDroneMap. Nell'interfaccia di WebODM le trovi nel pannello "Opzioni" quando crei un task; da riga di comando le passi come argomenti. Questa guida le elenca tutte, spiegando in italiano cosa fanno e quando ha senso toccarle.

Come leggere le tabelle#

  • Default è il valore usato se non tocchi l'opzione. Le opzioni "interruttore" (senza valore) sono disattivate per default: indicarle le attiva.
  • Le unità: risoluzioni in cm/px, distanze in metri, accuratezze in metri.
  • "Quando cambiarla" è un consiglio editoriale nostro, basato sull'esperienza e sulla documentazione; non sostituisce una prova sul tuo dataset.
  • In WebODM molte opzioni sono già combinate nei preset: prima di modificare a mano, parti dal preset più vicino al tuo caso.

1. Dataset e camera#

Opzioni che riguardano la lettura delle immagini e il modello di camera.

Opzione Default Cosa fa Quando cambiarla
--project-path <percorso> — Cartella del progetto che contiene images/ (solo riga di comando) Sempre, da CLI; WebODM la gestisce da solo
--name <nome> code Nome della sottocartella del progetto (solo CLI) Per tenere più progetti nella stessa cartella
--camera-lens <tipo> auto Modello di distorsione della lente: auto, perspective, brown, fisheye, fisheye_opencv, spherical, equirectangular, dual Camere fisheye (GoPro, alcune action cam) o a 360° (spherical/equirectangular); con auto il motore sceglie in base all'EXIF
--cameras <json> — Parametri interni della camera (calibrazione) da un file JSON o da un task precedente Per riusare una calibrazione già stimata su un dataset migliore, tipico con superfici uniformi o poca texture
--use-fixed-camera-params disattivata Blocca i parametri di camera durante la compensazione invece di stimarli Insieme a --cameras, quando ti fidi della calibrazione fornita più di quella che il dataset permetterebbe di stimare
--use-exif disattivata Usa le posizioni EXIF per georeferenziare anche se è presente un file GCP Raro; per confrontare un risultato con e senza GCP senza rimuovere il file
--rolling-shutter disattivata Attiva la correzione della distorsione da otturatore a tendina (rolling shutter) Camere senza otturatore meccanico (molti droni consumer) quando servono precisioni elevate
--rolling-shutter-readout <ms> 0 Tempo di lettura del sensore in millisecondi; 0 usa il valore del database interno per la camera rilevata Se la tua camera non è nel database o il valore è noto da misure; vedi casi particolari
--ignore-gsd disattivata Ignora il GSD stimato e non limita risoluzione di ortofoto e DEM al valore realistico Solo se sai perché: aumenta molto memoria e tempo per produrre pixel "inventati". Sconsigliata
--version — Stampa la versione del motore Per la relazione tecnica
--help — Elenco delle opzioni della versione installata Per verificare cosa supporta il tuo motore

2. Feature e matching#

La prima fase del calcolo: estrazione dei punti caratteristici (feature) in ogni immagine e ricerca delle corrispondenze tra immagini.

Opzione Default Cosa fa Quando cambiarla
--feature-quality <livello> high Risoluzione a cui vengono estratte le feature: ultra, high, medium, low, lowest. Livelli più alti trovano più punti ma costano memoria e tempo ultra su vegetazione, superfici uniformi o dataset con poche corrispondenze; medium/low per prove rapide o macchine con poca RAM
--feature-type <tipo> dspsift Algoritmo di estrazione: akaze, dspsift, hahog, orb, sift Il default è la scelta migliore nella maggior parte dei casi; orb è più veloce e meno accurato; akaze può aiutare con texture particolari
--min-num-features <n> 10000 Numero minimo di feature da estrarre per immagine Alzarlo (20.000–30.000) su vegetazione, campi, neve, sabbia; alzarlo costa tempo e memoria
--matcher-type <tipo> flann Algoritmo di matching: bow, bruteforce, flann bruteforce è più lento e più esaustivo, utile se il matching fallisce; bow più veloce su dataset grandi
--matcher-neighbors <n> 0 Numero di immagini vicine (per posizione GPS) con cui tentare il matching; 0 lascia decidere al motore Alzarlo se il volo ha molta sovrapposizione e mancano collegamenti; abbassarlo per velocizzare voli regolari
--matcher-order <n> 0 Numero di immagini vicine per ordine di scatto (nome file) con cui tentare il matching; 0 disattivato Per dataset senza GPS o da video, dove la sequenza è l'unico indizio di vicinanza
--bg-removal disattivata Sperimentale. Genera maschere automatiche per rimuovere lo sfondo Oggetti fotografati "girandogli intorno" (statue, veicoli) con sfondo che disturba; verificare i risultati
--sky-removal disattivata Sperimentale. Genera maschere per escludere il cielo dalle immagini Voli obliqui o a bassa quota con molto cielo nelle foto

3. Structure from Motion (SfM)#

La ricostruzione delle posizioni delle camere e della nuvola sparsa.

Opzione Default Cosa fa Quando cambiarla
--sfm-algorithm <tipo> incremental Algoritmo di ricostruzione: incremental (generale), triangulation (richiede posizioni GPS accurate e assetti), planar (scene piane, molto più veloce) planar per campi agricoli e aree piatte con volo nadir regolare; triangulation con droni RTK e dati di assetto affidabili
--sfm-no-partial disattivata Impedisce la ricostruzione di sottomodelli parziali quando il dataset non si collega in un unico blocco Se preferisci un errore chiaro a un risultato a pezzi
--use-hybrid-bundle-adjustment disattivata Compensazione ibrida: più veloce su dataset molto grandi, leggermente meno accurata Oltre 1.000 immagini, quando i tempi di SfM diventano un problema

4. Nuvola densa#

La generazione della nuvola di punti densa e i filtri applicati prima di mesh e DEM.

Opzione Default Cosa fa Quando cambiarla
--pc-quality <livello> medium Densità della nuvola: ultra, high, medium, low, lowest. È il parametro che più incide su tempo e memoria dopo il numero di immagini high per DEM e modelli 3D di dettaglio; ultra solo con macchine potenti e su aree piccole; low per ortofoto veloci
--pc-filter <n> 5 Rimuove i punti la cui distanza dalla superficie supera n deviazioni standard; 0 disattiva il filtro Abbassare (2–3) per pulire di più su vegetazione o rumore; alzare o azzerare per conservare strutture sottili (pali, cavi, spigoli)
--pc-sample <m> 0 Sottocampiona la nuvola in modo che due punti non siano più vicini di m metri; 0 disattivato Per alleggerire nuvole enormi prima di mesh e DEM, su grandi aree
--pc-classify disattivata Classifica i punti in terreno e non terreno (algoritmo SMRF, vedi §6) Necessaria se vuoi una nuvola classificata per il CAD/GIS; il DTM la attiva internamente
--pc-rectify disattivata Corregge la classificazione del terreno riempiendo buchi e rimuovendo punti isolati Con --pc-classify o --dtm su terreni con vegetazione
--pc-skip-geometric disattivata Salta la fase di consistenza geometrica nella densificazione: più veloce, un po' più rumoroso Per guadagnare tempo su dataset grandi quando la qualità della nuvola non è critica

5. Mesh e texture#

Costruzione della superficie triangolata (mesh) e applicazione delle immagini come texture.

Opzione Default Cosa fa Quando cambiarla
--mesh-size <n> 200000 Numero massimo di vertici della mesh Alzare (500.000–1.000.000) per modelli 3D di edifici e monumenti; abbassare per ortofoto rapide
--mesh-octree-depth <n> 11 Profondità dell'octree nella ricostruzione della superficie (1–14). Valori più alti danno più dettaglio 12–13 per edifici e oggetti con spigoli, insieme a --mesh-size più alto; costo in memoria elevato sopra 12
--use-3dmesh disattivata Usa la mesh 3D completa per generare l'ortofoto, invece della mesh 2.5D Scene con molte strutture verticali (edifici, ponti, muri): meno artefatti ai bordi verticali nell'ortofoto
--skip-3dmodel disattivata Non genera il modello 3D texturizzato completo; produce solo la mesh 2.5D per l'ortofoto Quando ti serve solo l'ortofoto o il DEM: risparmi molto tempo
--texturing-keep-unseen-faces disattivata Mantiene nella mesh le facce non viste da nessuna camera (senza texture) Per avere una superficie chiusa, per esempio in stampa 3D o volumi
--texturing-single-material disattivata Produce un unico file di texture invece di più tessere Per esportare verso software che gestiscono male più materiali
--texturing-skip-global-seam-leveling disattivata Salta l'equalizzazione globale del colore tra le immagini Solo con dati multispettrali o radiometrici in cui il valore del pixel non va alterato

6. DEM: DSM, DTM e filtro del terreno#

Modelli di elevazione: DSM (superficie, con vegetazione ed edifici) e DTM (terreno nudo).

Opzione Default Cosa fa Quando cambiarla
--dsm disattivata Genera il modello digitale della superficie (DSM) Sempre, se ti servono quote, curve di livello o volumi
--dtm disattivata Genera il modello digitale del terreno (DTM), classificando e rimuovendo gli oggetti sopra il suolo Calcolo di volumi di terreno, idraulica, progettazione; attiva internamente --pc-classify
--dem-resolution <cm/px> 5 Risoluzione di DSM e DTM in cm/px. Il motore la limita a un valore realistico rispetto al GSD (salvo --ignore-gsd) Impostarla a 2–3 volte il GSD è realistico; valori troppo fini producono rumore, non dettaglio
--dem-gapfill-steps <n> 3 Numero di passi di riempimento dei buchi nel DEM, con raggi crescenti; 0 disattiva Aumentare (4–5) su vegetazione o acqua con molti buchi; 0 se preferisci vedere dove mancano dati
--dem-decimation <n> 1 Sottocampiona la nuvola prima di generare il DEM: 1 usa tutti i punti, 100 uno su cento Per velocizzare il DEM su nuvole enormi, accettando meno dettaglio
--dem-euclidean-map disattivata Genera una mappa della distanza di ogni pixel dal dato più vicino (utile per capire dove il DEM è interpolato) In lavori dove devi documentare le aree riempite per interpolazione
--smrf-scalar <n> 1.25 Parametro del filtro SMRF: fattore che scala la soglia in base alla pendenza Vedi tabella seguente
--smrf-slope <n> 0.15 Pendenza massima del terreno considerata (adimensionale, 0,15 ≈ 15 %) Alzarlo (0,3–0,5) su terreni collinari o scoscesi; troppo alto e i tetti diventano "terreno"
--smrf-threshold <m> 0.5 Soglia di altezza in metri sopra la quale un punto non è terreno Abbassare (0,2–0,3) per terreni lisci; alzare (1–2) se il DTM segue la vegetazione bassa
--smrf-window <m> 18.0 Dimensione in metri della finestra di analisi; deve superare la dimensione dell'oggetto più grande da rimuovere Alzare (30–50) per edifici grandi o boschi fitti; abbassare per aree piccole e oggetti minuti

Il filtro SMRF (Simple Morphological Filter) è quello che separa terreno e oggetti per il DTM. I quattro parametri vanno provati insieme: cambia uno alla volta e confronta il DTM. Approfondimento nella guida a DSM, DTM e curve di livello.

7. Ortofoto e area di elaborazione#

Opzione Default Cosa fa Quando cambiarla
--orthophoto-resolution <cm/px> 5 Risoluzione dell'ortofoto in cm/px; limitata al GSD realistico salvo --ignore-gsd Impostarla vicino al GSD del volo (per esempio 2 con GSD 1,8 cm/px); più fine non aggiunge informazione
--orthophoto-compression <tipo> DEFLATE Compressione del GeoTIFF: JPEG, LZW, PACKBITS, DEFLATE, LZMA, NONE JPEG per file molto più piccoli quando la perdita è accettabile; NONE se un software a valle non gestisce la compressione
--orthophoto-cutline disattivata Calcola e salva una linea di taglio (cutline) per unire ortofoto adiacenti senza cuciture visibili Progetti in più parti da mosaicare in QGIS; attivata automaticamente con split-merge
--orthophoto-no-tiled disattivata Salva il GeoTIFF a strisce invece che a tessere Solo per compatibilità con software vecchi
--orthophoto-png disattivata Esporta anche una copia PNG dell'ortofoto Per condividere un'anteprima senza software GIS
--orthophoto-kmz disattivata Esporta anche un KMZ per Google Earth Per presentazioni e sopralluoghi
--fast-orthophoto disattivata Salta la nuvola densa e costruisce l'ortofoto dalla nuvola sparsa: molto più veloce Ortofoto rapide di aree piatte; sconsigliata con edifici o dislivelli, dove produce deformazioni
--skip-orthophoto disattivata Non genera l'ortofoto Quando ti servono solo nuvola, mesh o DEM
--crop <m> 3 Ritaglia i bordi dei risultati di n metri per eliminare le zone marginali di scarsa qualità; 0 disattiva Alzare per voli con bordi molto deformati; 0 se ogni metro conta e i bordi sono buoni
--boundary <geojson> — Limita l'elaborazione a un poligono GeoJSON (o a un file .geojson) Escludere acqua, aree private, zone fuori dal rilievo; riduce tempo e artefatti
--auto-boundary disattivata Calcola automaticamente un confine dalle posizioni delle camere e ritaglia i risultati Voli regolari: elimina le zone ai bordi con poca sovrapposizione senza disegnare un poligono
--auto-boundary-distance <m> 0 Distanza dalle posizioni camera usata da --auto-boundary; 0 la stima dal dataset Se il confine automatico è troppo stretto o troppo largo

Approfondimenti nella guida all'ortofoto.

8. Georeferenziazione: GCP, geo e GPS#

Opzione Default Cosa fa Quando cambiarla
--gcp <file> — File dei punti di controllo a terra (gcp_list.txt); in WebODM si carica insieme alle immagini Sempre, per un rilievo con accuratezza assoluta; formato nella guida sui GCP
--geo <file> — File geo.txt con posizioni (e assetti) esterni delle camere, al posto dell'EXIF Droni PPK, post-processing GNSS esterno; formato nella guida RTK/PPK
--gps-accuracy <m> 3 Accuratezza attesa delle posizioni GPS delle immagini, usata come peso nella compensazione Abbassare (0,1 circa) con droni RTK/PPK; alzare (5–10) con GPS scadente per lasciare più libertà al modello
--gps-z-offset <m> 0 Offset costante aggiunto alle quote GPS delle immagini Correggere un offset noto tra quota EXIF e quota di riferimento; non sostituisce i GCP
--force-gps disattivata Usa le posizioni GPS delle immagini anche quando è presente un file GCP Drone RTK con GCP: le due fonti si rafforzano
--align <file o "auto"> — Allinea i risultati a un DEM o a una nuvola di punti di riferimento (file) oppure, con auto, al task precedente Rilievi ripetuti nel tempo dello stesso sito, per confronti e change detection coerenti

9. Split e merge (dataset grandi)#

Opzione Default Cosa fa Quando cambiarla
--split <n> 999999 Numero medio di immagini per sottomodello; sotto questa soglia il dataset non viene diviso 400–800 su dataset oltre 1.000–1.500 immagini o quando la RAM non basta
--split-overlap <m> 150 Sovrapposizione in metri tra sottomodelli adiacenti Alzare su terreni con poca texture o voli ad alta quota; abbassare per risparmiare tempo su voli densi
--split-image-groups <file> — File di testo che assegna ogni immagine a un gruppo, per controllare la divisione a mano Voli in più giornate o più batterie, per dividere lungo i confini reali
--sm-cluster <url> — URL di un ClusterODX/ClusterODM che distribuisce i sottomodelli su più nodi Quando hai più macchine; vedi NodeODM e ClusterODM
--sm-no-align disattivata Salta l'allineamento tra sottomodelli dopo la ricostruzione Solo se l'allineamento peggiora il risultato, per esempio con GCP ben distribuiti in ogni sottomodello
--merge <cosa> all Cosa unire dopo lo split: all, pointcloud, orthophoto, dem Per produrre solo l'output che ti serve e risparmiare tempo
--merge-skip-blending disattivata Salta la fusione (blending) dei colori tra le ortofoto dei sottomodelli, la fase più lenta del merge Quando il tempo conta più delle cuciture visibili, o per un'anteprima rapida del mosaico

Il flusso completo è nella guida ai dataset grandi.

10. Multispettrale#

Opzione Default Cosa fa Quando cambiarla
--radiometric-calibration <tipo> none Calibrazione radiometrica: none, camera (usa i parametri della camera per convertire in riflettanza), camera+sun (aggiunge il sensore di irradianza solare, se presente) Camere multispettrali per indici di vegetazione; camera+sun se il drone ha il sensore di luce
--primary-band <nome> auto Banda usata per la ricostruzione geometrica; le altre vengono allineate a questa Se auto sceglie una banda con poche feature, indica una banda più contrastata (per esempio la NIR)
--skip-band-alignment disattivata Salta l'allineamento tra bande Solo se le bande sono già registrate a monte

Approfondimento nella guida NDVI e multispettrale.

11. Video#

Opzione Default Cosa fa Quando cambiarla
--video-limit <n> 500 Numero massimo di fotogrammi estratti da ogni video caricato Alzare per video lunghi di aree grandi; abbassare per prove rapide
--video-resolution <px> 4000 Dimensione massima in pixel del lato lungo dei fotogrammi estratti Abbassare se il video è di qualità modesta o per risparmiare memoria

Il video è una fonte comoda ma povera: fotogrammi compressi, rolling shutter, nessun GPS per fotogramma. Vedi la guida ai casi particolari.

12. Output e formati#

Opzione Default Cosa fa Quando cambiarla
--pc-las disattivata Esporta la nuvola densa anche in formato LAS (non compresso) Software che non leggono LAZ
--pc-copc disattivata Esporta la nuvola in COPC (Cloud Optimized Point Cloud), LAZ con indice spaziale Visualizzazione via web e QGIS recenti; sostituisce EPT in molti casi
--pc-ept disattivata Esporta la nuvola in formato EPT (Entwine Point Tiles) Viewer web basati su EPT
--pc-csv disattivata Esporta la nuvola in CSV Scambio con fogli di calcolo o software semplici; file molto grandi
--cog disattivata Salva ortofoto e DEM come Cloud Optimized GeoTIFF Pubblicazione su web o server, lettura parziale via rete
--build-overviews disattivata Aggiunge piramidi (overview) al GeoTIFF dell'ortofoto Apertura più fluida in QGIS su file grandi
--tiles disattivata Genera tessere (tiles) statiche per mappe web di ortofoto e DEM Pubblicare su un sito senza server GIS
--gltf disattivata Esporta il modello 3D anche in glTF/GLB Viewer web, Blender, condivisione
--3d-tiles disattivata Esporta il modello 3D e la nuvola in formato 3D Tiles (Cesium) Pubblicazione su globi 3D e piattaforme che usano Cesium
--skip-report disattivata Non genera il report PDF di qualità Solo per prove; per un lavoro il report va sempre prodotto e conservato

Formati e utilizzo nelle guide alla nuvola di punti, al modello 3D e all'export in QGIS.

13. Controllo del flusso, risorse e ripetizioni#

Opzione Default Cosa fa Quando cambiarla
--rerun <fase> — Ripete solo la fase indicata, usando i risultati esistenti delle altre Rigenerare un solo prodotto dopo aver cambiato un'opzione di quella fase
--rerun-from <fase> — Ripete la fase indicata e tutte le successive Cambiare per esempio --dem-resolution senza rifare SfM e nuvola densa: --rerun-from odm_dem
--rerun-all disattivata Cancella tutto e ricomincia da zero Quando hai cambiato immagini o GCP
--end-with <fase> odm_postprocess Ferma l'elaborazione dopo la fase indicata Fermarsi a opensfm per verificare la ricostruzione sparsa prima di investire ore nella nuvola densa
--copy-to <percorso> — Copia i risultati in un'altra cartella al termine (solo CLI) Archiviazione automatica su un disco o una condivisione di rete
--optimize-disk-space disattivata Elimina i file intermedi man mano che non servono più. Impedisce --rerun e --rerun-from Dataset grandi su dischi piccoli; non usarla se prevedi di rilanciare fasi
--max-concurrency <n> 4 (secondo la scheda tecnica; nella documentazione ODM corrisponde al numero di core disponibili) Numero massimo di processi paralleli. Il picco di memoria cresce con il numero di thread Abbassarlo se vai in out of memory; alzarlo su macchine con molti core e molta RAM
--no-gpu disattivata Disattiva l'uso della GPU anche se disponibile Problemi con driver o risultati diversi tra CPU e GPU; la GPU accelera solo l'estrazione feature

Le fasi (in ordine) usate da --rerun, --rerun-from e --end-with sono: dataset, split, merge, opensfm, openmvs, odm_filterpoints, odm_meshing, mvs_texturing, odm_georeferencing, odm_dem, odm_orthophoto, odm_report, odm_postprocess.

In WebODM il pulsante "Riavvia" di un task permette di scegliere da quale fase ripartire: usa internamente --rerun-from. Funziona solo se il nodo ha conservato i file intermedi, quindi non con --optimize-disk-space e non dopo una pulizia del nodo.

14. Combinazioni tipiche#

Qualche combinazione di partenza, da adattare al tuo dataset. In WebODM puoi salvarle come preset personalizzati.

Ortofoto rapida di un'area piatta (verifica di cantiere, agricoltura):

testo
--fast-orthophoto --skip-3dmodel --auto-boundary --orthophoto-resolution 3

Ortofoto e DSM/DTM di qualità per un rilievo topografico con GCP:

testo
--dsm --dtm --dem-resolution 4 --orthophoto-resolution 2 --pc-quality high --feature-quality high --auto-boundary

Aggiungi il file gcp_list.txt tra le immagini caricate.

Modello 3D di un edificio con foto oblique:

testo
--pc-quality high --mesh-size 600000 --mesh-octree-depth 12 --use-3dmesh --gltf

Volo con drone RTK e alcuni GCP:

testo
--gps-accuracy 0.1 --force-gps --dsm --pc-quality high

Dataset di 3.000 immagini su una macchina con 32 GB di RAM:

testo
--split 500 --split-overlap 150 --optimize-disk-space --skip-3dmodel --pc-quality medium

Ogni combinazione è spiegata in dettaglio nelle guide su tempi e memoria, dataset grandi e casi particolari.

Come verificare

Per sapere quali opzioni ha effettivamente usato un task, apri il report PDF: nella sezione riepilogativa sono elencate le opzioni non predefinite. Da riga di comando, il file log.json nella cartella del progetto contiene l'elenco completo. Se un'opzione che hai impostato non compare, controlla il nome (i trattini, le maiuscole) e la versione del motore con --help o nel pannello informazioni del nodo in WebODM. Il risultato è coerente con le opzioni se, per esempio, la risoluzione dell'ortofoto in QGIS corrisponde a quella richiesta (o al GSD, se l'hai chiesta più fine) e il DTM è presente quando hai attivato --dtm.

Problemi frequenti#

Un'opzione non esiste nella mia versione. ODX e ODM divergono dal 2026, e le versioni precedenti alla 3.0 avevano nomi diversi (per esempio --resize-to, --depthmap-resolution, rimosse). Consulta --help e le pagine ufficiali linkate in testa.

Cambio un'opzione e il risultato non cambia. Se hai usato "Riavvia da" una fase successiva a quella su cui l'opzione agisce, il motore non l'ha rieseguita. Per esempio --min-num-features richiede di ripartire da opensfm, --dem-resolution da odm_dem.

Out of memory dopo aver alzato la qualità. --feature-quality ultra, --pc-quality ultra, --mesh-octree-depth 13+ e --ignore-gsd sono le cause tipiche. Torna al default e cambia una cosa alla volta; vedi ottimizzare tempi e memoria.

L'ortofoto non ha la risoluzione richiesta. Il motore la limita al GSD reale. Non usare --ignore-gsd per aggirare il limite: otterresti pixel interpolati, non dettaglio.

Prossimi passi#

Fonti

Guide correlate

Segnala un errore in questa pagina
Siti ufficiali (esterni): WebODM — webodm.org⁠Documentazione WebODM — docs.webodm.org⁠OpenDroneMap — opendronemap.org⁠Documentazione OpenDroneMap — docs.opendronemap.org⁠