# Depth Anything V2

## Обзор

Depth Anything V2 был представлен в [одноимённой статье](https://huggingface.co/papers/2406.09414) Ли Хэ Янга и соавторов. Он использует ту же архитектуру, что и исходная модель [Depth Anything](depth_anything), но применяет синтетические данные и teacher-модель большей ёмкости, что позволяет получать значительно более точные и устойчивые предсказания глубины.

Аннотация из статьи следующая:

*В данной работе представлена модель Depth Anything V2. Не прибегая к сложным приёмам, мы стремимся выявить ключевые закономерности, которые помогут создать мощную модель однокамерной оценки глубины. В частности, по сравнению с версией V1, эта версия обеспечивает значительно более точные и устойчивые предсказания глубины благодаря трём основным подходам: 1) замене всех размеченных реальных изображений на синтетические, 2) увеличению ёмкости нашей teacher-модели и 3) обучению student-моделей с использованием моста из реальных изображений с псевдо-разметкой в большом масштабе. По сравнению с новейшими моделями, построенными на базе Stable Diffusion, наши модели значительно эффективнее (более чем в 10 раз быстрее) и точнее. Мы предоставляем модели разного масштаба (от 25M до 1.3B параметров) для поддержки широкого спектра сценариев. Благодаря их высокой способности к обобщению, мы дообучаем их с метрическими метками глубины, чтобы получить наши метрические модели глубины. Помимо наших моделей, учитывая ограниченное разнообразие и частые шумы в текущих тестовых наборах, мы создали универсальный оценочный бенчмарк с точными аннотациями и разнообразными сценами, чтобы содействовать будущим исследованиям.*

<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/depth_anything_overview.jpg"
alt="drawing" width="600"/>

 Обзор Depth Anything. Из оригинальной статьи.

Модели Depth Anything были предоставлены [nielsr](https://huggingface.co/nielsr). Исходный код можно найти [здесь](https://github.com/DepthAnything/Depth-Anything-V2).

## Пример использования

Существует два основных способа использования Depth Anything V2: либо через API pipeline, который скрывает от вас всю сложность, либо самостоятельно, используя класс `DepthAnythingForDepthEstimation`.

### API Pipeline

Пайплайн позволяет использовать модель всего в нескольких строках кода:

```python
import requests
from PIL import Image

from transformers import pipeline

# load pipe
pipe = pipeline(task="depth-estimation", model="depth-anything/Depth-Anything-V2-Small-hf")

# load image
url = 'http://images.cocodataset.org/val2017/000000039769.jpg'
image = Image.open(requests.get(url, stream=True).raw)

# inference
depth = pipe(image)["depth"]
```

### Использование модели самостоятельно

Если вы хотите выполнять предобработку и постобработку самостоятельно, вот как это сделать:

```python
import requests
import torch
from PIL import Image

from transformers import AutoImageProcessor, AutoModelForDepthEstimation

url = "http://images.cocodataset.org/val2017/000000039769.jpg"
image = Image.open(requests.get(url, stream=True).raw)

image_processor = AutoImageProcessor.from_pretrained("depth-anything/Depth-Anything-V2-Small-hf")
model = AutoModelForDepthEstimation.from_pretrained("depth-anything/Depth-Anything-V2-Small-hf", device_map="auto")

# prepare image for the model
inputs = image_processor(images=image, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

# interpolate to original size and visualize the prediction
post_processed_output = image_processor.post_process_depth_estimation(
    outputs,
    target_sizes=[(image.height, image.width)],
)

predicted_depth = post_processed_output[0]["predicted_depth"]
depth = (predicted_depth - predicted_depth.min()) / (predicted_depth.max() - predicted_depth.min())
depth = depth.detach().cpu().numpy() * 255
depth = Image.fromarray(depth.astype("uint8"))
```

## Ресурсы

Список официальных ресурсов Hugging Face и сообщества (отмечены значком 🌎), которые помогут вам начать работу с Depth Anything.

- [Руководство по задаче оценки монокулярной глубины](../tasks/monocular_depth_estimation)
- [Демо Depth Anything V2](https://huggingface.co/spaces/depth-anything/Depth-Anything-V2).
- Ноутбук с демонстрацией инференса с помощью [DepthAnythingForDepthEstimation](/docs/transformers/v5.23.0/ru/model_doc/depth_anything#transformers.DepthAnythingForDepthEstimation) доступен [здесь](https://github.com/NielsRogge/Transformers-Tutorials/blob/master/Depth%20Anything/Predicting_depth_in_an_image_with_Depth_Anything.ipynb). 🌎
- [Конвертация в Core ML варианта `small` для использования на Apple Silicon](https://huggingface.co/apple/coreml-depth-anything-v2-small).

Если вы хотите предложить ресурс для включения в этот раздел, пожалуйста, создайте Pull Request, и мы его рассмотрим! В идеале ресурс должен демонстрировать что-то новое, а не дублировать существующие материалы.

## DepthAnythingConfig[[transformers.DepthAnythingConfig]]

#### transformers.DepthAnythingConfig[[transformers.DepthAnythingConfig]]

```python
transformers.DepthAnythingConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, backbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, patch_size: int | list[int] | tuple[int, int] = 14, initializer_range: float = 0.02, reassemble_hidden_size: int = 384, reassemble_factors: list[int | float] | tuple[int | float, ...] = (4, 2, 1, 0.5), neck_hidden_sizes: list[int] | tuple[int, ...] = (48, 96, 192, 384), fusion_hidden_size: int = 64, head_in_index: int = -1, head_hidden_size: int = 32, depth_estimation_type: str = 'relative', max_depth: int | None = 1)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/depth_anything/configuration_depth_anything.py#L25)

**Параметры:**

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *необязательный*) : Конфигурация базовой модели.

patch_size (`Union[int, list[int], tuple[int, int]]`, *необязательный*, по умолчанию `14`) : Размер (разрешение) каждого патча.

initializer_range (`float`, *необязательный*, по умолчанию `0.02`) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

reassemble_hidden_size (`int`, *optional*, по умолчанию 384) : Количество входных каналов в слоях reassemble.

reassemble_factors (`list[int]`, *необязательный*, по умолчанию `[4, 2, 1, 0.5]`) : Коэффициенты увеличения/уменьшения в слоях reassemble.

neck_hidden_sizes (`list[str]`, *необязательный*, по умолчанию `[48, 96, 192, 384]`) : Скрытые размеры, к которым выполняется проекция для карт признаков бэкбона.

fusion_hidden_size (`int`, *необязательный*, по умолчанию 64) : Количество каналов до слияния.

head_in_index (`int`, *optional*, по умолчанию -1) : Индекс признаков, используемых в голове оценки глубины.

head_hidden_size (`int`, *optional*, по умолчанию 32) : Количество выходных каналов во втором свёртке головы оценки глубины.

depth_estimation_type (`str`, *необязательный*, по умолчанию `"relative"`) : Тип оценки глубины. Может быть одним из `["relative", "metric"]`.

max_depth (`float`, *optional*) : Максимальная глубина, используемая для головы оценки глубины "metric". Для внутренних моделей следует использовать значение 20, а для внешних — 80. При оценке относительной глубины это значение игнорируется.

Это класс конфигурации для хранения настроек модели Depth AnythingModel. Он используется для создания модели Depth Anything в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [LiheYoung/depth-anything-small-hf](https://huggingface.co/LiheYoung/depth-anything-small-hf)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig).

Пример:

```python
>>> from transformers import DepthAnythingConfig, DepthAnythingForDepthEstimation

>>> # Initializing a DepthAnything small style configuration
>>> configuration = DepthAnythingConfig()

>>> # Initializing a model from the DepthAnything small style configuration
>>> model = DepthAnythingForDepthEstimation(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## DepthAnythingForDepthEstimation[[transformers.DepthAnythingForDepthEstimation]]

#### transformers.DepthAnythingForDepthEstimation[[transformers.DepthAnythingForDepthEstimation]]

```python
transformers.DepthAnythingForDepthEstimation(config: DepthAnythingConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/depth_anything/modeling_depth_anything.py#L316)

**Параметры:**

config ([DepthAnythingConfig](/docs/transformers/v5.23.0/ru/model_doc/depth_anything#transformers.DepthAnythingConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Depth Anything Model с головой для оценки глубины (состоящей из 3 свёрточных слоёв), например, для KITTI, NYUv2.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.DepthAnythingForDepthEstimation.forward]]

```python
forward(pixel_values: Tensor, labels: typing.Optional[torch.LongTensor] = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, **kwargs)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/depth_anything/modeling_depth_anything.py#L327)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [DPTImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/dpt#transformers.DPTImageProcessor). Подробности см. в [DPTImageProcessor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) (`processor_class` использует [DPTImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/dpt#transformers.DPTImageProcessor) для обработки изображений).

labels (`torch.LongTensor` формы `(batch_size, height, width)`, *необязательный*) : Карты истинной глубины для вычисления функции потерь.

output_attentions (`bool`, *необязательный*) : Нужно ли возвращать тензоры внимания всех слоев внимания. Подробнее см. `attentions` в разделе возвращаемых тензоров.

output_hidden_states (`bool`, *необязательный*) : Нужно ли возвращать скрытые состояния всех слоёв. Подробнее о `hidden_states` в разделе возвращаемых тензоров.

return_dict (`bool`, *необязательный*) : Нужно ли возвращать [ModelOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.utils.ModelOutput) вместо обычного кортежа.

**Возвращает:** [DepthEstimatorOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.DepthEstimatorOutput) или `tuple(torch.Tensor)`

Объект [DepthEstimatorOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.DepthEstimatorOutput) или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([DepthAnythingConfig](/docs/transformers/v5.23.0/ru/model_doc/depth_anything#transformers.DepthAnythingConfig)) и входных данных.

Метод forward класса [DepthAnythingForDepthEstimation](/docs/transformers/v5.23.0/ru/model_doc/depth_anything#transformers.DepthAnythingForDepthEstimation) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потери классификации (или регрессии, если config.num_labels==1).
- **predicted_depth** (`torch.Tensor` формы `(batch_size, height, width)`) -- Предсказанная глубина для каждого пикселя.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или когда `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, num_channels, height, width)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
- **attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, patch_size, sequence_length)`.

  Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

Примеры:
```python
>>> from transformers import AutoImageProcessor, AutoModelForDepthEstimation
>>> import torch
>>> import numpy as np
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> image_processor = AutoImageProcessor.from_pretrained("LiheYoung/depth-anything-small-hf")
>>> model = AutoModelForDepthEstimation.from_pretrained("LiheYoung/depth-anything-small-hf")

>>> # prepare image for the model
>>> inputs = image_processor(images=image, return_tensors="pt")

>>> with torch.no_grad():
...     outputs = model(**inputs)

>>> # interpolate to original size
>>> post_processed_output = image_processor.post_process_depth_estimation(
...     outputs,
...     target_sizes=[(image.height, image.width)],
... )

>>> # visualize the prediction
>>> predicted_depth = post_processed_output[0]["predicted_depth"]
>>> depth = predicted_depth * 255 / predicted_depth.max()
>>> depth = depth.detach().cpu().numpy()
>>> depth = Image.fromarray(depth.astype("uint8"))
```

