Estimativa de Profundidade Monocular com Ultralytics YOLO#

A estimativa de profundidade monocular prevê um mapa de profundidade por píxel a partir de uma única imagem RGB. Cada píxel de saída contém um valor de profundidade em metros que representa a distância estimada entre a câmara e esse ponto da superfície.

A saída de um modelo de profundidade é um mapa denso de floats com forma (H, W), alinhado com a imagem de entrada. Esta representação por píxel torna a estimativa de profundidade monocular adequada para reconstrução de cenas 3D, navegação de robôs, criação de conteúdo de RA/RV e qualquer aplicação que necessite da disposição espacial a partir de uma única câmara.

Modelos#

Os modelos de profundidade YOLO26 pré-treinados numa ampla combinação de vários conjuntos de dados (interior + exterior, ~2,19M de imagens) são apresentados abaixo. As colunas de métricas são reportadas na divisão de teste Eigen do NYU Depth V2.

Os modelos são descarregados automaticamente da versão mais recente da Ultralytics na primeira utilização.

• delta1^NYU é a percentagem de píxeis em que a profundidade prevista está dentro de um fator de 1,25 da verdade fundamental, na divisão de teste Eigen do NYU Depth V2 (654 imagens), com TTA multiescala + inversão horizontal e alinhamento por mínimos quadrados logarítmicos.
• A precisão em escala única sem TTA pode ser reproduzida com yolo depth val model=yolo26n-depth.pt data=nyu-depth.yaml imgsz=768 device=0 (substitui model= por cada tamanho), que usa alinhamento mediano (apenas de escala) e obtém pontuações inferiores: delta1 0,783 (n), 0,793 (s), 0,840 (m), 0,853 (l), 0,860 (x).
• abs_rel é o erro relativo absoluto médio entre os valores de profundidade previstos e os da verdade fundamental.
• rmse é a raiz do erro quadrático médio em metros.
• Velocidade é a latência apenas da inferência (excluindo o pré e pós-processamento) em imgsz=768, batch=1, reportada como média ± desvio-padrão ao longo de execuções cronometradas após o aquecimento. CPU ONNX é o ONNX Runtime fp32 num Intel Xeon de 32 núcleos (Skylake); T4 TensorRT10 é TensorRT fp16 numa Tesla T4.
• parâmetros e FLOPs são medidos a 768×768, a resolução de treino dos pesos disponibilizados.

Consulta a pré-visualização não lançada do YOLO27 para resultados preliminares do NYU Depth V2.

Velocidade comparada com Depth Anything V2#

Depth Anything V2 é uma baseline aberta amplamente utilizada para profundidade monocular. O seu backbone DINOv2 de vision transformer e o descodificador DPT exigem muitos recursos computacionais; por isso, na mesma Tesla T4 com TensorRT fp16, o menor modelo Depth Anything V2 disponibilizado é mais lento do que todos os modelos de profundidade YOLO26 — incluindo o YOLO26x-depth, que tem mais do dobro de parâmetros.

A ~768 px — imgsz=768 para YOLO26, a resolução em que os seus pesos disponibilizados são treinados, e 770 px para Depth Anything V2, cujo backbone DINOv2 requer um múltiplo do seu tamanho de patch de 14:

A ~640 px — imgsz=640 e 644 px, respetivamente — a ordenação mantém-se, e YOLO26n-depth é 5,9× mais rápido do que Depth Anything V2 Small:

• A latência refere-se apenas à inferência, batch=1, TensorRT fp16 numa Tesla T4 — o mesmo sistema de teste da tabela de modelos acima, apresentado aqui com duas casas decimais; FPS é o recíproco da latência não arredondada. As colunas de Aceleração dividem a latência de Depth Anything V2 Small (20,99 ms) e Base (55,40 ms) pela latência do YOLO26.
• Depth Anything V2 Small e Base são os checkpoints ViT-S e ViT-B disponibilizados.
• A comparação abrange apenas a latência — as duas famílias de modelos não são avaliadas aqui segundo um protocolo de precisão comum.

Intervalo de profundidade e a cabeça de log-profundidade#

A cabeça de profundidade prevê exp(logit) — sem limites (~0,02–150 m) — e desacopla a forma da cena da escala absoluta: a rede prevê um campo de log-profundidade relativo, e os metros absolutos são definidos por uma transformação separada de dois parâmetros (exp(a·log d + b)), recuperada durante a avaliação, através de calibração leve ou por ajuste fino. A alternativa comum, uma cabeça sigmoid × max_depth limitada, incorpora antes um limite máximo fixo na arquitetura, pelo que qualquer profundidade além de max_depth é truncada — o que impede o treino e a previsão de cenas a maior distância.

Porque é que a cabeça não tem limites: evidências em diferentes intervalos de profundidade#

A/B controlado — os mesmos dados, o mesmo agendamento, apenas a cabeça é diferente. Treino de ambas as cabeças desde o início numa combinação idêntica de dados de interior (≤10 m) e exterior (≤80 m):

A cabeça limitada não consegue representar a maioria dos píxeis exteriores a >10 m, pelo que deixa de melhorar quase imediatamente; a cabeça log aprende a partir de todo o intervalo.

O modo de falha que corrige — ajuste fino num único conjunto de dados, estratificado por intervalo. O ajuste fino de uma cabeça limitada (10 m) em conjuntos de dados individuais funciona quando os dados cabem no limite e entra em colapso quando o ultrapassam:

O colapso ocorre exatamente no limite máximo. A cabeça log não tem esse limite.

Modelos disponibilizados — desempenho entre intervalos. A família disponibilizada com cabeça log, avaliada em benchmarks que abrangem 10 m (NYU, iBims-1) a 80 m (KITTI), com δ1 alinhado à escala:

Ambas as colunas são apresentadas conforme publicadas. As outras linhas são avaliadas com o protocolo de TTA e mínimos quadrados logarítmicos descrito nas páginas dos respetivos conjuntos de dados, que o validador neste repositório não implementa; por isso, a linha KITTI não pode ser novamente medida em condições equivalentes. A página do KITTI apresenta, em vez disso, valores medidos na divisão Eigen canónica de 652 frames.

Os maiores ganhos verificam-se nos benchmarks exteriores de maior alcance (KITTI, ETH3D) — precisamente onde um limite fixo de 10 m é mais prejudicial —, enquanto o desempenho em interiores é mantido.

Treinar#

Treina YOLO26n-depth no conjunto de dados Depth8 durante 100 épocas, com tamanho de imagem 640. Para obter uma lista completa dos argumentos disponíveis, consulta a página de Configuração.

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 os detalhes completos do modo train na página Treinar.

Ajuste fino nos teus próprios dados#

Ao adaptares um modelo de profundidade pré-treinado a um conjunto de dados personalizado, reduz a taxa de aprendizagem e usa o otimizador AdamW. As predefinições do otimizador estão ajustadas para treinar desde o início (SGD com lr0=0.01); aplicadas a um modelo de profundidade já convergido, podem substituir o conhecimento pré-treinado e degradar os resultados — especialmente ao fazer ajuste fino num único domínio.

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
)

Dicas adicionais:

• A ampliação é controlada pelos argumentos padrão (degrees, translate, scale, shear, perspective, flipud, fliplr, hsv_h, hsv_s, hsv_v); a deformação geométrica e as inversões são aplicadas de forma idêntica ao mapa de profundidade emparelhado. Para veres a receita exata utilizada nos pesos YOLO26-Depth disponibilizados, inspeciona o train_args armazenado no checkpoint — consulta Inspecionar os argumentos de treino do checkpoint YOLO26.
• mosaic, mixup, cutmix e copy_paste não estão implementados para profundidade. O carregador de conjuntos de dados de profundidade define automaticamente estas probabilidades como 0, pelo que transmiti-las não tem qualquer efeito. Estas ampliações não são suportadas porque combinam várias imagens, o que produziria mapas de profundidade emparelhados inválidos.
• Qualquer intervalo de profundidade funciona imediatamente. Os modelos com cabeça log preveem profundidade sem limites, pelo que se adaptam a dados de curto alcance (macro) ou longo alcance (exteriores/condução) sem alterações. Definir max_depth: no YAML do teu conjunto de dados (em metros) limita quais os píxeis GT contabilizados para as métricas de validação.
• Mantém o desempenho geral. Se precisares que o modelo continue preciso em cenas para além do teu conjunto de treino, mistura uma pequena fração (~5–10%) de imagens gerais diversificadas nos teus dados de treino; isto reduz substancialmente o esquecimento durante o ajuste fino.
• Treina desde o início (model=yolo26s-depth.yaml) apenas se o teu domínio for muito diferente e tiveres um conjunto de dados grande — nesse caso, o SGD padrão lr0=0.01 é adequado, pois não há pesos pré-treinados a preservar.

Calibrar a escala de profundidade#

A cabeça de profundidade separa a forma (estrutura relativa da cena) da escala (metros absolutos). Se um modelo já produzir uma boa profundidade relativa nas tuas cenas, mas os valores absolutos estiverem incorretos para a tua câmara, podes corrigir a escala em segundos com model.calibrate() — um ajuste fechado log-afim de dois parâmetros sobre um pequeno conjunto rotulado, sem treino de gradientes e sem alterar os pesos da rede, pelo que não pode degradar a estrutura 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")

A calibração precisa de profundidade ground truth para ajustar-se, por isso é executada numa divisão com rótulos — não pode ocorrer durante a inferência às cegas. Ela ajusta-se e calcula as pontuações nos mesmos píxeis avaliados pelas métricas de validação: valores GT iguais ou superiores a max_depth do YAML do dataset (100 m por predefinição) são excluídos. Usa-a quando a profundidade relativa já é boa e apenas a escala/alcance está incorreta; se a própria estrutura relativa precisar de mudar para o teu domínio, faz fine-tuning.

O treino faz isto automaticamente: depois de model.train(...) terminar, os melhores checkpoints e os últimos checkpoints são calibrados no conjunto de validação para produzirem profundidade com escala métrica desde o início.

Os checkpoints yolo26*-depth.pt disponibilizados já incluem esta calibração, ajustada com a mistura de validação do pré-treino. Trata-se de uma única escala global em todos os domínios; por isso, para obter a profundidade absoluta mais precisa numa câmara ou tipo de cenário específico, executa model.calibrate() numa pequena divisão com rótulos dos teus próprios dados — isso substitui o ajuste incorporado.

Formato do dataset#

Os datasets de estimativa de profundidade associam cada imagem RGB a um PNG de profundidade uint16 escalado ou a um mapa de profundidade NPY de ponto flutuante em metros. Por predefinição, os valores PNG usam milímetros; os datasets com outra convenção definem depth_scale no respetivo YAML. O carregador obtém o caminho da profundidade substituindo o componente images por depth, dando preferência a .png e usando .npy como alternativa.

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

Por exemplo, uma imagem em images/train/scene_001.jpg é associada a um mapa de profundidade em depth/train/scene_001.png. Consulta o Guia de Datasets de Estimativa de Profundidade para obter a especificação completa do formato.

Validação#

Valida a precisão de um modelo YOLO26n-depth treinado num dataset de estimativa de profundidade. Especifica data explicitamente para que a validação use o YAML do dataset pretendido. Os pesos disponibilizados foram treinados em imgsz=768; por isso, valida e faz previsões nesse tamanho para obter a melhor precisão.

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

Previsão#

Usa um modelo YOLO26n-depth treinado para executar previsões em imagens.

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 todos os detalhes do modo predict na página Predict.

Saída dos resultados#

A estimativa de profundidade YOLO devolve um objeto Results por imagem. Cada resultado armazena um mapa de profundidade denso de ponto flutuante para a imagem completa.

Para consultar os campos Results específicos da tarefa em todas as tarefas, vê a secção Resultados de Previsão por Tarefa.

Colorir o mapa de profundidade#

O mapa de profundidade bruto é um array de ponto flutuante de um único canal, em metros — útil para cálculos, mas difícil de interpretar diretamente. Para o converter numa imagem a cores, usa o auxiliar colorize_depth em ultralytics.utils.plotting, que mapeia o array de profundidade (H, W) para uma imagem BGR (H, W, 3) uint8 (os píxeis inválidos <= 0 são apresentados a preto).

result.plot() já sobrepõe esta colorização à imagem de entrada usando as predefinições (cmap="jet", mode="disparity"); chama colorize_depth diretamente quando quiseres uma imagem de profundidade colorida autónoma ou um mapa de cores ou uma normalização diferentes.

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")

Todos os mapas de cores vão de frio/escuro → quente/brilhante. mode determina qual das extremidades representa o que está perto, enquanto vmin/vmax fixa o intervalo entre frames para que uma cor represente sempre a mesma distância.

Exportação#

Exporta um modelo YOLO26n-depth para um formato diferente, como ONNX, CoreML, etc.

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")

Os formatos de exportação disponíveis para estimativa de profundidade YOLO26 estão na tabela abaixo. Podes exportar para qualquer formato usando o argumento format, por exemplo, format='onnx' ou format='engine'. Podes fazer previsões ou validações diretamente em modelos exportados, por exemplo, yolo predict model=yolo26n-depth.onnx. Os exemplos de utilização do teu modelo são apresentados após a conclusão da exportação.

nms=None por padrão utiliza saídas brutas para NMS externo. Define nms=False para selecionar uma cabeça livre de NMS disponível; os formatos não suportados recorrem ao seu caminho de saída nativo. As entradas nms acima identificam formatos que podem incorporar NMS com nms=True.

Consulta todos os detalhes de export na página Export.

Perguntas frequentes#