Estimativa de profundidade

Definição

A tarefa depth prevê um valor por pixel a partir de uma única imagem RGB. O LibreYOLO define esse valor como profundidade inversa relativa: maior significa mais perto da câmera, e os números não carregam unidade métrica nem uma escala que se mantenha entre duas imagens. Comparar a profundidade entre dois pixels da mesma predição faz sentido; comparar um valor com o valor de outra imagem, não.

Uma predição preenche result.depth_map, um payload DepthMap que guarda um array (H, W) sobre o canvas da imagem original. .min, .max e .mean leem os valores finitos, e .normalized() reescala o mapa para [0, 1] para exibição. result.boxes fica vazio, então conf, iou e max_det não têm efeito, e save=True grava uma imagem do mapa com mapa de cores aplicado, em vez de uma foto anotada.

Modelos

As seguintes famílias atendem a depth.

Depth Anything V2 combina um encoder DINOv2 com um decoder DPT e é a opção padrão de uso geral aqui. O licenciamento decide o tamanho tanto quanto a acurácia: o checkpoint Small é Apache-2.0, enquanto Base e Large são de uso não comercial, então confira a tabela de checkpoints na página dele antes de escolher um.

Depth Anything 3 porta o checkpoint DA3MONO-LARGE, um transformer comum, sem nenhuma especialização arquitetural para profundidade.

ZipDepth é o nível compacto: uma CNN reparametrizável destilada do Depth Anything V2 Large, com um segundo checkpoint cujo decoder evita operações de gather e unfold para compiladores de NPU que não as têm.

MiDaS é a linha de trabalho que estabeleceu o protocolo de profundidade relativa zero-shot usado para medir as outras famílias. Seus checkpoints s e l são baixados de espelhos do LibreYOLO sob a licença MIT do publicador.

LibreMODUS chega à profundidade como um dos alvos de um modelo any-to-any, e não como uma cabeça dedicada. Precisa do extra modus e da sua própria conta autenticada no Hugging Face, e não oferece nem val() nem export().

SenseNova-Vision gera o mapa de profundidade como uma imagem por meio de um decode por difusão, a partir do mesmo checkpoint de 7B que atende suas outras seis tarefas. Precisa do extra sensenova, e seus pesos são restritos a uso não comercial; a licença está na página dele.

Marigold V2 adiciona adaptadores de profundidade baseados em difusão com codificações de profundidade explícitas.

GTR prediz profundidade métrica e a retorna como profundidade inversa relativa, então 1 / result.depth_map.data recupera metros em cenas parecidas com os seus dados de treinamento. Roda no pacote base, treina e exporta para ONNX e TorchScript.

Predição

Os pesos são baixados no primeiro uso e ficam em cache localmente. As páginas de modelo descrevem os requisitos de autenticação e runtime.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreDepthAnythingV2s-depth.pt")result = model(SAMPLE_IMAGE, save=True) depth = result.depth_mapprint(depth.data.shape)              # (H, W) no canvas originalprint(depth.min, depth.max, depth.mean)

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreDepthAnythingV2s-depth.pt")result = model(SAMPLE_IMAGE) depth = result.depth_mapraw = depth.data          # maior é mais perto; sem unidade métrica, sem escalagray = depth.normalized() # reescalado para [0, 1] para visualizaçãoprint(raw.shape, float(gray.max()))

from libreyolo import LibreYOLO, SAMPLE_IMAGE # Mesmo contrato de tarefa, uma rede bem menor feita para runtimes de borda (edge).model = LibreYOLO("LibreZipDepthb-depth.pt")result = model(SAMPLE_IMAGE) print(result.depth_map.data.shape)

A resolução de entrada tem restrições por família. Depth Anything V2 e Depth Anything 3 usam uma grade de patches DINOv2, então imgsz deve ser divisível exatamente por 14, o que o LibreYOLO verifica antes de rodar. Results.plot() renderiza resultados de profundidade. Veja predição para fontes, streaming e tratamento de resultados.

DepthMap.encoding é inverse_depth por padrão e pode ser depth ou log_depth. A validação interpreta a codificação antes do alinhamento afim. A codificação não dá escala métrica a predições relativas.

Formato do dataset

A validação de profundidade emparelha cada imagem com um mapa de profundidade denso de canal único e mesma resolução, encontrado ao substituir o diretório de profundidade no caminho da imagem.

dataset/  data.yaml  images/    val/room.jpg  depths/    val/room.png

path: datasetval: images/valdepths_dir: depthsnc: 1names: {0: depth}

Os mapas são PNG ou TIF de canal único, ou .npy. Os valores são profundidade pura em uma unidade que o dataset mantém consistente, e pixels 0, negativos, NaN e infinitos marcam amostras inválidas, que ficam de fora das métricas. Mapas inteiros são divididos por depth_scale, cujo padrão é 256.0, a convenção dos PNG de 16 bits; mapas .npy em ponto flutuante são usados como estão. depth_stem_suffix e depth_mask_suffix cobrem datasets que nomeiam de outro jeito seus arquivos de profundidade ou suas máscaras de validade. Veja formatos de dataset para o contrato completo.

Treinamento

GTR é a única família de profundidade que treina: train() em um checkpoint -depth roda a receita upstream dela, descrita na página de modelo. Nas outras famílias, train() gera NotImplementedError. Cada página de modelo indica o script de conversão que transforma um checkpoint treinado upstream em um que o LibreYOLO pode carregar.

Validação

val() roda o validador de profundidade compartilhado. A profundidade relativa não tem escala absoluta, então cada predição é primeiro ajustada ao inverso do seu ground truth com uma escala e um deslocamento de mínimos quadrados calculados por imagem, e depois invertida de volta para profundidade. Todas as métricas abaixo são calculadas por imagem sobre esse mapa alinhado, com média sobre o dataset, contando apenas os pixels que o dataset marca como válidos.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDepthAnythingV2s-depth.pt")metrics = model.val(data="my-dataset.yaml") print(metrics["metrics/abs_rel"])print(metrics["metrics/rmse"])print(metrics["metrics/delta1"])   # fitnessprint(metrics["metrics/delta2"], metrics["metrics/delta3"])

metrics/abs_rel é o erro relativo absoluto médio, o resíduo dividido pela profundidade do ground truth, e quanto menor, melhor. metrics/rmse é a raiz do erro quadrático médio na própria unidade de profundidade do dataset, também quanto menor, melhor. metrics/delta1, metrics/delta2 e metrics/delta3 são as acurácias por limiar: a fração de pixels válidos cuja razão em relação ao ground truth, tomada na direção que for maior, fica abaixo de 1.25, de 1.25 ao quadrado e de 1.25 ao cubo, então quanto maior, melhor. metrics/delta1 também é o fitness, o número que a seleção do melhor checkpoint lê.

Exportação

Um modelo de profundidade exportado é carregado de volta por LibreYOLO() pelo sufixo do arquivo, então um arquivo .onnx ou .engine se comporta como um checkpoint e devolve o mesmo Results, com depth_map no lugar dos boxes.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDepthAnythingV2s-depth.pt")model.export(format="onnx")

from libreyolo import LibreYOLO, SAMPLE_IMAGE # A factory decide pelo sufixo do arquivo, então um artefato exportado# carrega como qualquer checkpoint e devolve o mesmo objeto Results.model = LibreYOLO("LibreDepthAnythingV2s-depth.onnx")result = model(SAMPLE_IMAGE) print(result.depth_map.data.shape)

A cobertura varia por família, e o Depth Anything 3 rejeita qualquer formato fora do seu conjunto validado em vez de tentar uma conversão não validada. Confira a página do modelo e a matriz completa de exportação antes de se comprometer com um alvo. LibreMODUS e SenseNova-Vision não exportam de jeito nenhum. Exportação lista os argumentos que cada formato aceita.