Stima della profondità monoculare con Ultralytics YOLO#

La stima della profondità monoculare predice una mappa di profondità per pixel a partire da una singola immagine RGB. Ogni pixel di output contiene un valore di profondità in metri che rappresenta la distanza stimata dalla fotocamera a quel punto della superficie.

L'output di un modello di profondità è una mappa float densa di forma (H, W), allineata all'immagine di input. Questa rappresentazione per pixel rende la stima della profondità monoculare adatta alla ricostruzione di scene 3D, alla navigazione dei robot, alla creazione di contenuti AR/VR e a qualsiasi applicazione che richieda la disposizione spaziale a partire da una singola fotocamera.

Modelli#

Di seguito sono mostrati i modelli di profondità YOLO26 preaddestrati su un'ampia combinazione di dataset (interni + esterni, ~2,19 M di immagini). Le colonne delle metriche riportano i risultati sullo split di test Eigen di NYU Depth V2.

I modelli vengono scaricati automaticamente dall'ultima release di Ultralytics al primo utilizzo.

• delta1^NYU è la percentuale di pixel per i quali la profondità predetta rientra in un fattore di 1,25 rispetto al ground truth, sullo split di test Eigen di NYU Depth V2 (654 immagini), con TTA multi-scala + inversione orizzontale e allineamento ai minimi quadrati nel logaritmo.
• La precisione a scala singola senza TTA è riproducibile con yolo depth val model=yolo26n-depth.pt data=nyu-depth.yaml imgsz=768 device=0 (sostituisci model= per ogni dimensione), che usa un allineamento mediano (solo scala) e ottiene punteggi inferiori: delta1 0,783 (n), 0,793 (s), 0,840 (m), 0,853 (l), 0,860 (x).
• abs_rel è l'errore relativo assoluto medio tra i valori di profondità predetti e quelli del ground truth.
• rmse è la radice dell'errore quadratico medio, espressa in metri.
• Velocità è la latenza relativa esclusivamente all'inferenza (escludendo pre/post-processing) a imgsz=768, batch=1, riportata come media ± deviazione standard sulle esecuzioni cronometrate dopo il warmup. CPU ONNX è ONNX Runtime fp32 su un Intel Xeon a 32 core (Skylake); T4 TensorRT10 è TensorRT fp16 su una Tesla T4.
• params e FLOPs sono misurati a 768×768, la risoluzione di training dei pesi rilasciati.

Consulta la anteprima non rilasciata di YOLO27 per i risultati preliminari su NYU Depth V2.

Velocità a confronto con Depth Anything V2#

Depth Anything V2 è una baseline open ampiamente utilizzata per la profondità monoculare. Il suo backbone DINOv2 vision transformer e il decoder DPT richiedono molte risorse di calcolo, quindi sulla stessa Tesla T4 con TensorRT fp16 il modello Depth Anything V2 rilasciato più piccolo è più lento di ogni modello di profondità YOLO26, incluso YOLO26x-depth, che ha più del doppio dei parametri.

A ~768 px — imgsz=768 per YOLO26, la risoluzione alla quale sono stati addestrati i pesi rilasciati, e 770 px per Depth Anything V2, il cui backbone DINOv2 richiede un multiplo della dimensione della patch pari a 14:

A ~640 px — imgsz=640 e 644 px rispettivamente — l'ordine non cambia e YOLO26n-depth è 5,9× più veloce di Depth Anything V2 Small:

• La latenza riguarda esclusivamente l'inferenza, batch=1, TensorRT fp16 su una Tesla T4 — lo stesso harness della tabella dei modelli sopra, mostrata qui con due cifre decimali; gli FPS sono il reciproco della latenza non arrotondata. Le colonne Accelerazione dividono la latenza di Depth Anything V2 Small (20,99 ms) e Base (55,40 ms) per la latenza di YOLO26.
• Depth Anything V2 Small e Base sono i checkpoint ViT-S e ViT-B rilasciati.
• Il confronto riguarda solo la latenza: qui le due famiglie di modelli non vengono valutate secondo un protocollo di accuratezza condiviso.

Intervallo di profondità e head log-depth#

La head di profondità predice exp(logit) — senza limiti (~0,02–150 m) — e separa la forma della scena dalla scala assoluta: la rete predice un campo di log-depth relativo e i metri assoluti vengono impostati da una trasformazione separata a due parametri (exp(a·log d + b)), ricavata durante la valutazione, tramite una calibrazione leggera o mediante fine-tuning. L'alternativa comune, una head sigmoid × max_depth con intervallo limitato, incorpora invece nell'architettura un limite massimo fisso, quindi qualsiasi profondità oltre max_depth viene troncata, impedendo il training e la predizione di scene a maggiore distanza.

Perché la head non ha limiti: evidenze su diversi intervalli di profondità#

A/B controllato — stessi dati, stesso programma, cambia solo la head. Addestrando entrambe le head da zero su una combinazione identica di dati interni (≤10 m) ed esterni (≤80 m):

La head con intervallo limitato non può rappresentare la maggior parte dei pixel esterni oltre i 10 m, quindi smette di migliorare quasi immediatamente; la head log apprende dall'intero intervallo.

Il problema che risolve — fine-tuning su un singolo dataset, stratificato per intervallo. Il fine-tuning di una head con limite (10 m) su singoli dataset funziona quando i dati rientrano nel limite e crolla quando lo superano:

Il crollo si verifica esattamente al confine del limite. La head log non presenta questo confine.

Modelli rilasciati — prestazioni su più intervalli. La famiglia rilasciata con head log, valutata su benchmark che vanno da 10 m (NYU, iBims-1) a 80 m (KITTI), con δ1 allineato alla scala:

Entrambe le colonne sono riportate come pubblicate. Le altre righe vengono valutate con il protocollo TTA e dei minimi quadrati nel logaritmo descritto nelle pagine dei rispettivi dataset, che il validator in questo repository non implementa; pertanto la riga KITTI non può essere nuovamente misurata alle stesse condizioni. La pagina KITTI riporta invece i valori misurati sullo split Eigen canonico da 652 frame.

I miglioramenti maggiori si osservano nei benchmark esterni a maggiore distanza (KITTI, ETH3D), esattamente dove un limite fisso di 10 m penalizza maggiormente, mentre le prestazioni negli ambienti interni vengono mantenute.

Addestramento#

Addestra YOLO26n-depth sul dataset Depth8 per 100 epoche con dimensione delle immagini pari a 640. Per un elenco completo degli argomenti disponibili, consulta la pagina Configurazione.

from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n-depth.yaml")  # build a new model from YAML
model = YOLO("yolo26n-depth.pt")  # load a pretrained model (recommended for training)
model = YOLO("yolo26n-depth.yaml").load("yolo26n-depth.pt")  # build from YAML and transfer weights

# Train the model
results = model.train(data="depth8.yaml", epochs=100, imgsz=640)

Consulta i dettagli completi della modalità train nella pagina Train.

Fine-tuning sui tuoi dati#

Quando adatti un modello di profondità preaddestrato a un dataset personalizzato, riduci il learning rate e usa l'ottimizzatore AdamW. Le impostazioni predefinite dell'ottimizzatore sono ottimizzate per il training da zero (SGD con lr0=0.01); applicate a un modello di profondità già convergente, possono sovrascrivere le conoscenze preaddestrate e peggiorare i risultati, soprattutto durante il fine-tuning su un singolo dominio.

from ultralytics import YOLO

model = YOLO("yolo26s-depth.pt")  # start from pretrained weights

model.train(
    data="path/to/your_dataset.yaml",
    epochs=20,
    imgsz=640,
    optimizer="AdamW",
    lr0=1e-4,  # ~100x below the from-scratch default
    warmup_bias_lr=1e-4,  # keep warmup gentle too
)

Suggerimenti aggiuntivi:

• L'augmentation è controllata dagli args standard (degrees, translate, scale, shear, perspective, flipud, fliplr, hsv_h, hsv_s, hsv_v); la deformazione geometrica e i flip vengono applicati in modo identico alla mappa di profondità associata. Per vedere la procedura esatta usata per i pesi YOLO26-Depth rilasciati, esamina train_args, memorizzato nel checkpoint — consulta Ispezione degli argomenti di training del checkpoint YOLO26.
• mosaic, mixup, cutmix e copy_paste non sono implementati per la profondità. Il data loader della profondità imposta automaticamente queste probabilità a 0, quindi passarle non ha alcun effetto. Queste augmentation non sono supportate perché combinano più immagini, producendo mappe di profondità associate non valide.
• Qualsiasi intervallo di profondità funziona immediatamente. I modelli con head log predicono una profondità senza limiti, quindi si adattano a dati a corto raggio (macro) o a lungo raggio (esterni/guida) senza modifiche. L'impostazione di max_depth: nel file YAML del dataset (in metri) determina quali pixel GT contribuiscono alle metriche di validazione.
• Mantieni le prestazioni generali. Se hai bisogno che il modello rimanga accurato su scene oltre quelle del training set, inserisci nei dati di training una piccola frazione (~5–10%) di immagini generiche diversificate; questo riduce sostanzialmente l'oblio durante il fine-tuning.
• Addestra da zero (model=yolo26s-depth.yaml) solo se il tuo dominio è molto diverso e disponi di un dataset ampio; in questo caso l'SGD predefinito lr0=0.01 è appropriato, poiché non ci sono pesi preaddestrati da preservare.

Calibrazione della scala di profondità#

La head di profondità separa la forma (struttura relativa della scena) dalla scala (metri assoluti). Se un modello produce già una buona profondità relativa sulle tue scene, ma i valori assoluti non sono corretti per la tua fotocamera, puoi correggere la scala in pochi secondi con model.calibrate(): un fit in forma chiusa di un modello log-affine a due parametri su un piccolo set etichettato, senza training del gradiente e senza modificare i pesi della rete, quindi senza degradare la struttura relativa.

from ultralytics import YOLO

model = YOLO("yolo26s-depth.pt")

# Fit scale on a labeled split (~100+ images is enough), then persist it
model.calibrate(data="path/to/your_dataset.yaml")
model.save("yolo26s-depth-calibrated.pt")

La calibrazione richiede la profondità di riferimento con cui effettuare il fitting, quindi viene eseguita su uno split con annotazioni: non può avvenire durante un'inferenza alla cieca. Esegue il fitting e calcola i punteggi sugli stessi pixel valutati dalle metriche di validazione: i valori GT pari o superiori a max_depth del file YAML del dataset (100 m per impostazione predefinita) vengono esclusi. Usala quando la profondità relativa è già buona e il problema riguarda solo scala/intervallo; se invece per il tuo dominio deve cambiare anche la struttura relativa, esegui il fine-tuning.

L'addestramento lo fa automaticamente: dopo il completamento di model.train(...), i checkpoint migliore e più recente vengono calibrati sul set di validazione, così producono subito una profondità scalata metricamente.

I checkpoint yolo26*-depth.pt rilasciati includono già questa calibrazione, ottenuta sul mix di validazione del preaddestramento. Si tratta di un'unica scala globale per tutti i domini; per ottenere la massima accuratezza della profondità assoluta su una fotocamera o un tipo di scena specifico, esegui model.calibrate() su un piccolo split con annotazioni dei tuoi dati: sostituirà il fitting incluso nel modello.

Formato del dataset#

I dataset per la stima della profondità associano ogni immagine RGB a una mappa di profondità PNG uint16 scalata o a una mappa di profondità NPY in virgola mobile, espressa in metri. Per impostazione predefinita, i valori PNG usano i millimetri; i dataset con un'altra convenzione impostano depth_scale nel file YAML. Il loader ricava il percorso della profondità sostituendo il componente images con depth, preferendo .png e usando .npy come fallback.

dataset/
├── images/
│   ├── train/
│   └── val/
└── depth/
    ├── train/
    └── val/

Ad esempio, un'immagine in images/train/scene_001.jpg viene associata a una mappa di profondità in depth/train/scene_001.png. Consulta la Guida ai dataset per la stima della profondità per la specifica completa del formato.

Val#

Valuta l'accuratezza di un modello YOLO26n-depth addestrato su un dataset per la stima della profondità. Passa esplicitamente data in modo che la validazione utilizzi il file YAML del dataset previsto. I pesi rilasciati sono addestrati a imgsz=768, quindi per ottenere la massima accuratezza esegui validazione e predizione a quella dimensione.

from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n-depth.pt")  # load an official model
model = YOLO("path/to/best.pt")  # load a custom model

# Validate the model
metrics = model.val(data="nyu-depth.yaml")
metrics.delta1  # percentage of pixels within threshold δ=1.25
metrics.abs_rel  # mean absolute relative error
metrics.rmse  # root mean squared error (meters)
metrics.silog  # scale-invariant logarithmic error

Predizione#

Usa un modello YOLO26n-depth addestrato per eseguire predizioni sulle immagini.

from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n-depth.pt")  # load an official model
model = YOLO("path/to/best.pt")  # load a custom model

# Predict with the model
results = model("https://ultralytics.com/images/bus.jpg")  # predict on an image

# Access the results
for result in results:
    depth_map = result.depth.data.cpu().numpy()  # torch.Tensor -> NumPy float32, shape (H, W), meters

Consulta la pagina Predict per tutti i dettagli sulla modalità predict.

Output dei risultati#

La stima della profondità YOLO restituisce un oggetto Results per ogni immagine. Ogni risultato contiene una mappa di profondità densa in virgola mobile per l'intera immagine.

Per i campi Results specifici dell'attività in tutte le attività, consulta la sezione Risultati delle predizioni per attività.

Colorazione della mappa di profondità#

La mappa di profondità grezza è un array float a canale singolo in metri: utile per i calcoli, ma difficile da leggere direttamente. Per trasformarla in un'immagine a colori, usa l'helper colorize_depth in ultralytics.utils.plotting, che mappa l'array di profondità (H, W) in un'immagine BGR (H, W, 3) uint8 (i pixel non validi <= 0 vengono visualizzati in nero).

result.plot() applica già questa colorazione sull'immagine di input usando i valori predefiniti (cmap="jet", mode="disparity"); chiama direttamente colorize_depth quando vuoi un'immagine di profondità colorata autonoma oppure una mappa di colori o una normalizzazione diversi.

import cv2

from ultralytics import YOLO
from ultralytics.utils.plotting import colorize_depth

model = YOLO("yolo26n-depth.pt")
result = model("https://ultralytics.com/images/bus.jpg")[0]

depth = result.depth.data.cpu().numpy()  # (H, W) float32, meters

# Colorize with near = warm and save
cv2.imwrite("depth_colored.png", colorize_depth(depth, cmap="spectral"))  # (H, W, 3) BGR uint8

# Fix the range to 0-20 m so the same color means the same distance across frames
cv2.imwrite("depth_metric.png", colorize_depth(depth, vmin=0.0, vmax=20.0, cmap="inferno", mode="metric"))

# Blended overlay straight from the Results object (uses cmap="jet", mode="disparity")
result.save("depth_overlay.png")

Ogni mappa di colori va da freddo/scuro a caldo/chiaro. mode decide quale estremità rappresenta il vicino, mentre vmin/vmax fissano l'intervallo tra i frame, così un colore indica sempre la stessa distanza.

Esportazione#

Esporta un modello YOLO26n-depth in un formato diverso, come ONNX, CoreML e così via.

from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n-depth.pt")  # load an official model
model = YOLO("path/to/best.pt")  # load a custom model

# Export the model
model.export(format="onnx")

I formati di esportazione disponibili per la stima della profondità con YOLO26 sono riportati nella tabella seguente. Puoi esportare in qualsiasi formato usando l'argomento format, ad esempio format='onnx' o format='engine'. Puoi eseguire predizioni o validazioni direttamente sui modelli esportati, ad esempio yolo predict model=yolo26n-depth.onnx. Al termine dell'esportazione vengono mostrati esempi di utilizzo per il tuo modello.

nms=None utilizza i valori predefiniti per gli output grezzi per la NMS esterna. Imposta nms=False per selezionare una testa senza NMS disponibile; i formati non supportati ricorrono al loro percorso di output nativo. Le voci nms sopra indicano i formati che possono incorporare la NMS con nms=True.

Consulta la pagina Export per tutti i dettagli su export.

FAQ#