Hugging Face's logo

Transformers documentation

CHMv2

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Эта модель была опубликована в HF papers 06.03.2026 и добавлена в Hugging Face Transformers 11.03.2026.

CHMv2

FlashAttention SDPA

Обзор

Модель Canopy Height Maps v2 (CHMv2) была предложена в статье CHMv2: Improvements in Global Canopy Height Mapping using DINOv3. На основе наших исходных карт высоты крон высокого разрешения, выпущенных в 2024 году, CHMv2 обеспечивает существенное повышение точности, детализации и глобальной согласованности за счёт использования DINOv3 — самообучаемой визуальной модели от Meta.

Подробнее можно узнать здесь, а исходный код — здесь.

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

Точные данные о высоте кроны необходимы для количественной оценки лесного углерода, мониторинга восстановления и деградации лесов, а также для оценки структуры местообитаний, однако высококачественные измерения, полученные с помощью воздушного лазерного сканирования (ALS), остаются неравномерно доступными в глобальном масштабе. В данной работе мы представляем CHMv2 — глобальную карту высоты кроны с разрешением в метры, полученную на основе высокодетальных оптических спутниковых снимков с использованием модели оценки глубины, построенной на базе DINOv3 и обученной на моделях высоты кроны, полученных с помощью ALS. По сравнению с существующими продуктами, CHMv2 существенно повышает точность, снижает смещение в высоких лесах и лучше сохраняет мелкомасштабную структуру, такую как границы кроны и просветы. Эти улучшения стали возможны благодаря значительному расширению географически разнообразных обучающих данных, автоматизированной подготовке и регистрации данных, а также формулировке функции потерь и стратегии выборки данных, адаптированной к распределениям высоты кроны. Мы валидируем CHMv2 по независимым тестовым наборам ALS и по десяткам миллионов наблюдений GEDI и ICESat-2, демонстрируя стабильную производительность в основных лесных биомах.

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

Выполните инференс на изображении с помощью следующего кода:

import torch
from PIL import Image

from transformers import AutoImageProcessor, AutoModelForDepthEstimation


processor = AutoImageProcessor.from_pretrained("facebook/dinov3-vitl16-chmv2-dpt-head")
model = AutoModelForDepthEstimation.from_pretrained("facebook/dinov3-vitl16-chmv2-dpt-head", device_map="auto")

image = Image.open("image.tif")
inputs = processor(images=image, return_tensors="pt").to(model.device)

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

depth = processor.post_process_depth_estimation(
    outputs, target_sizes=[(image.height, image.width)]
)[0]["predicted_depth"]

CHMv2Config

класс transformers.CHMv2Config

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonebackbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonepatch_size: int = 16initializer_range: float = 0.02reassemble_factors: list[float | int] | None = Nonepost_process_channels: list[int] | None = Nonefusion_hidden_size: int = 256head_hidden_size: int = 128number_output_channels: int = 256readout_type: str = 'project'min_depth: float = 0.001max_depth: float = 96.0bins_strategy: typing.Literal['linear', 'log', 'chmv2_mixlog'] = 'chmv2_mixlog'norm_strategy: typing.Literal['linear', 'softmax', 'sigmoid', 'chmv2_mixlog'] = 'chmv2_mixlog' )

Параметры

  • backbone_config (Union[dict, "PreTrainedConfig"], необязательный) — Конфигурация модели-бэкбона. В настоящее время поддерживается только DINOv3ViTConfig.
  • patch_size (int, необязательный, по умолчанию 16) — Размер патча, используемый в базовом зрительном трансформере.
  • initializer_range (float, необязательный, по умолчанию 0.02) — Стандартное отклонение truncated_normal_initializer, используемое для инициализации всех матриц весов.
  • reassemble_factors (list[float], необязательный, по умолчанию [4, 2, 1, 0.5]) — Коэффициенты увеличения/уменьшения разрешения в слоях reassemble.
  • post_process_channels (list[int], необязательный, по умолчанию [128, 256, 512, 1024]) — Размеры выходных каналов этапа reassemble для каждого уровня признаков backbone.
  • fusion_hidden_size (int, необязательный, по умолчанию 256) — Число каналов до слияния.
  • head_hidden_size (int, необязательный, по умолчанию 128) — Число каналов в скрытом слое головы оценки глубины.
  • number_output_channels (int, необязательный, по умолчанию 256) — Количество выходных каналов для головы CHMv2 (количество глубинных бинов).
  • readout_type (str, необязательный, по умолчанию "project") — Тип операции readout для токена CLS. Одно из значений ["ignore", "add", "project"].
  • min_depth (float, необязательный, по умолчанию 0.001) — Минимальное значение глубины для вычисления бина глубины.
  • max_depth (float, необязательный, по умолчанию 96.0) — Максимальное значение глубины для вычисления бина глубины.
  • bins_strategy (str, необязательный, по умолчанию "chmv2_mixlog") — Стратегия распределения глубинных бинов. Одно из значений ["linear", "log", "chmv2_mixlog"].
  • norm_strategy (str, необязательный, по умолчанию "chmv2_mixlog") — Стратегия нормализации для предсказания глубины. Одно из значений ["linear", "softmax", "sigmoid", "chmv2_mixlog"].

Это класс конфигурации для хранения настроек модели Chmv2Model. Он используется для создания модели Chmv2 в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/dinov3-vitl16-chmv2-dpt-head

Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.

>>> from transformers import CHMv2Config, CHMv2ForDepthEstimation

>>> configuration = CHMv2Config()
>>> model = CHMv2ForDepthEstimation(configuration)
>>> configuration = model.config

CHMv2ImageProcessor

класс transformers.CHMv2ImageProcessor

< >

( **kwargs: *<class 'transformers.models.chmv2.image_processing_chmv2.CHMv2ImageProcessorKwargs'> )

Параметры

  • do_convert_rgb (bool, kwargs, optional) — Следует ли преобразовать изображение в RGB.
  • do_resize (bool, kwargs, optional, по умолчанию False) — Указывает, нужно ли изменить размер изображения.
  • size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, по умолчанию {'height' -- 384, 'width': 384}): Определяет максимальные размеры входных данных для модели.
  • default_to_square (bool, kwargs, optional, по умолчанию True) — Определяет, следует ли по умолчанию использовать квадратное изображение при изменении размера, если size задано как int.
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, по умолчанию None) — Размер выходного изображения после применения center_crop.
  • resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, по умолчанию 3) — Фильтр ресемплинга, используемый при изменении размера изображения. Может быть одним из значений перечисления PILImageResampling. Влияет только в том случае, если do_resize установлено в True.
  • do_rescale (bool, kwargs, optional, по умолчанию True) — Указывает, следует ли выполнять рескейлинг изображения.
  • rescale_factor (float, kwargs, optional, по умолчанию 0.00392156862745098) — Коэффициент масштабирования, применяемый к изображению, если do_rescale установлен в True.
  • do_normalize (bool, kwargs, optional, по умолчанию True) — Указывает, следует ли нормализовать изображение.
  • image_mean (Union[float, list[float], tuple[float, ...]], kwargs, optional, по умолчанию [0.42, 0.411, 0.296]) — Среднее значение изображения, используемое для нормализации. Влияет только в том случае, если do_normalize установлено в True.
  • image_std (Union[float, list[float], tuple[float, ...]], kwargs, optional, по умолчанию [0.213, 0.156, 0.143]) — Стандартное отклонение изображения, используемое для нормализации. Влияет только в том случае, если do_normalize установлено в True.
  • do_pad (bool, kwargs, optional, по умолчанию True) — Указывает, нужно ли выравнивать изображение. Выравнивание выполняется либо до максимального размера в батче, либо до фиксированного квадратного размера для каждого изображения. Конкретная стратегия выравнивания зависит от модели.
  • pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Размер в формате {"height": int, "width" int}, до которого следует дополнить изображения. Должен быть больше любого размера изображения, предоставленного для предобработки. Если pad_size не указан, изображения будут дополнены до наибольшей высоты и ширины в батче. Применяется только при do_pad=True.
  • do_center_crop (bool, kwargs, optional, по умолчанию None) — Выполнять ли центрированный обрез изображения.
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, optional) — Поддерживается только ChannelDimension.FIRST. Добавлено для совместимости с медленными процессорами.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, необязательный) — Формат размерности каналов для входного изображения. Если не задан, формат размерности каналов выводится из входного изображения. Может быть одним из:
    • "channels_first" или ChannelDimension.FIRST: изображение в формате (num_channels, height, width).
    • "channels_last" или ChannelDimension.LAST: изображение в формате (высота, ширина, число каналов).
    • "none" или ChannelDimension.NONE: изображение в формате (height, width).
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — Устройство, на котором будут обрабатываться видео. Если не задано, устройство определяется на основе входных видео.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Возвращает стопку тензоров, если установлено значение 'pt', иначе возвращает список тензоров.
  • disable_grouping (bool, kwargs, optional) — Определяет, следует ли отключить группировку изображений по размеру для их индивидуальной обработки, а не пачками. Если значение равно None, оно будет установлено в True, если изображения находятся на CPU, и в False в противном случае. Этот выбор основан на эмпирических наблюдениях, описанных здесь: https://github.com/huggingface/transformers/pull/38157
  • image_seq_length (int, kwargs, optional) — Количество токенов изображения, используемых для каждого изображения во входных данных. Добавлено для обратной совместимости, но в будущих моделях это значение следует задавать как атрибут процессора.
  • ensure_multiple_of (int, kwargs, optional, по умолчанию 1) — Если do_resize равно True, изображение масштабируется до размера, кратного этому значению. Может быть переопределено параметром ensure_multiple_of в preprocess.
  • size_divisor (int, kwargs, по умолчанию 16) — Размер, на который должны делиться как высота, так и ширина.
  • keep_aspect_ratio (bool, kwargs, необязательный, по умолчанию False) — Если True, изображение масштабируется до максимально возможного размера с сохранением соотношения сторон. Может быть переопределено параметром keep_aspect_ratio в preprocess.
  • do_reduce_labels (bool, kwargs, optional, по умолчанию self.do_reduce_labels) — Указывает, следует ли уменьшить все значения меток в сегментационных картах на 1. Обычно используется для наборов данных, где 0 обозначает фон, а сам фон не входит в число всех классов набора (например, ADE20k). Метка фона будет заменена на 255.

Создаёт процессор изображений CHMv2ImageProcessor.

preprocess

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]segmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.models.chmv2.image_processing_chmv2.CHMv2ImageProcessorKwargs'> ) → ~image_processing_base.BatchFeature

Параметры

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]) — Изображение для предобработки. Ожидается одно изображение или батч изображений со значениями пикселей в диапазоне от 0 до 255. Если передаются изображения со значениями пикселей в диапазоне от 0 до 1, установите do_rescale=False.
  • segmentation_maps (ImageInput, необязательный) — Сегментационные карты, которые необходимо предобработать.
  • do_convert_rgb (bool, kwargs, optional) — Следует ли преобразовать изображение в RGB.
  • do_resize (bool, kwargs, optional) — Указывает, нужно ли изменить размер изображения.
  • size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Описывает максимальные размеры входных данных для модели.
  • default_to_square (bool, kwargs, optional) — Определяет, следует ли по умолчанию использовать квадратное изображение при изменении размера, если size является целым числом.
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Размер выходного изображения после применения center_crop.
  • resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — Фильтр ресемплинга, используемый при изменении размера изображения. Может быть одним из значений перечисления PILImageResampling. Влияет только в том случае, если do_resize установлено в True.
  • do_rescale (bool, kwargs, optional) — Нужно ли перемасштабировать изображение.
  • rescale_factor (float, kwargs, optional) — Коэффициент масштабирования, применяемый к изображению, если do_rescale установлен в True.
  • do_normalize (bool, kwargs, optional) — Нужно ли нормализовать изображение.
  • image_mean (Union[float, list[float], tuple[float, ...]], kwargs, optional) — Среднее значение изображения, используемое для нормализации. Влияет только в том случае, если do_normalize установлено в True.
  • image_std (Union[float, list[float], tuple[float, ...]], kwargs, optional) — Стандартное отклонение изображения, используемое для нормализации. Влияет только в том случае, если do_normalize установлено в True.
  • do_pad (bool, kwargs, optional) — Определяет, нужно ли выравнивать изображение. Выравнивание выполняется либо до максимального размера в батче, либо до фиксированного квадратного размера для каждого изображения. Точная стратегия выравнивания зависит от модели.
  • pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Размер в формате {"height": int, "width" int}, до которого следует дополнить изображения. Должен быть больше любого размера изображения, предоставленного для предобработки. Если pad_size не указан, изображения будут дополнены до наибольшей высоты и ширины в батче. Применяется только при do_pad=True.
  • do_center_crop (bool, kwargs, optional) — Выполнять ли центрированную обрезку изображения.
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, optional) — Поддерживается только ChannelDimension.FIRST. Добавлено для совместимости с медленными процессорами.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, необязательный) — Формат размерности каналов для входного изображения. Если не задан, формат размерности каналов выводится из входного изображения. Может быть одним из:
    • "channels_first" или ChannelDimension.FIRST: изображение в формате (num_channels, height, width).
    • "channels_last" или ChannelDimension.LAST: изображение в формате (высота, ширина, число каналов).
    • "none" или ChannelDimension.NONE: изображение в формате (height, width).
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — Устройство, на котором будут обрабатываться видео. Если не задано, устройство определяется на основе входных видео.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Возвращает стопку тензоров, если установлено значение 'pt', иначе возвращает список тензоров.
  • disable_grouping (bool, kwargs, optional) — Определяет, следует ли отключить группировку изображений по размеру для их индивидуальной обработки, а не пачками. Если значение равно None, оно будет установлено в True, если изображения находятся на CPU, и в False в противном случае. Этот выбор основан на эмпирических наблюдениях, описанных здесь: https://github.com/huggingface/transformers/pull/38157
  • image_seq_length (int, kwargs, optional) — Количество токенов изображения, используемых для каждого изображения во входных данных. Добавлено для обратной совместимости, но в будущих моделях это значение следует задавать как атрибут процессора.
  • ensure_multiple_of (int, kwargs, optional, по умолчанию 1) — Если do_resize равно True, изображение масштабируется до размера, кратного этому значению. Может быть переопределено параметром ensure_multiple_of в preprocess.
  • size_divisor (int, kwargs) — Размер, на который должны делиться как высота, так и ширина.
  • keep_aspect_ratio (bool, kwargs, необязательный, по умолчанию False) — Если True, изображение масштабируется до максимально возможного размера с сохранением соотношения сторон. Может быть переопределено параметром keep_aspect_ratio в preprocess.
  • do_reduce_labels (bool, kwargs, optional, по умолчанию self.do_reduce_labels) — Указывает, следует ли уменьшить все значения меток в сегментационных картах на 1. Обычно используется для наборов данных, где 0 обозначает фон, а сам фон не входит в число всех классов набора (например, ADE20k). Метка фона будет заменена на 255.

Возвращает

~image_processing_base.BatchFeature

  • data (dict) — Словарь списков/массивов/тензоров, возвращаемый методом call (‘pixel_values’ и т. д.).
  • tensor_type (Union[None, str, TensorType], необязательный) — Здесь можно указать tensor_type, чтобы при инициализации преобразовать списки целых чисел в тензоры PyTorch/Numpy.

post_process_depth_estimation

< >

( outputs: DepthEstimatorOutputtarget_sizes: transformers.utils.generic.TensorType | list[tuple[int, int]] | None = None ) → List[Dict[str, TensorType]]

Параметры

  • outputs (DepthEstimatorOutput) — Сырые выходные данные модели.
  • target_sizes (TensorType or List[Tuple[int, int]], необязательный) — Тензор формы (batch_size, 2) или список кортежей (Tuple[int, int]), содержащий целевой размер (высота, ширина) каждого изображения в батче. Если значение не задано, предсказания не будут масштабироваться.

Возвращает

List[Dict[str, TensorType]]

Список словарей тензоров, представляющих обработанные предсказания глубины.

Преобразует необработанный вывод DepthEstimatorOutput в итоговые предсказания глубины и изображения глубины в формате PIL. Поддерживается только PyTorch.

CHMv2ForDepthEstimation

класс transformers.CHMv2ForDepthEstimation

< >

( config: CHMv2Config )

Параметры

  • config (CHMv2Config) — Класс конфигурации модели, содержащий все параметры модели. Инициализация по файлу конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод from_pretrained() для загрузки весов модели.

Модель CHMv2 с головкой для оценки глубины (состоящей из свёрточных слоёв), например, для оценки высоты крон деревьев.

Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)

Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

forward

< >

( pixel_values: Tensorlabels: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → DepthEstimatorOutput or tuple(torch.Tensor)

Параметры

  • pixel_values (torch.Tensor формы (batch_size, num_channels, image_size, image_size)) — Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью CHMv2ImageProcessor. Подробности см. в CHMv2ImageProcessor.call() (processor_class использует CHMv2ImageProcessor для обработки изображений).
  • labels (torch.LongTensor формы (batch_size, height, width), необязательный) — Истинные карты оценки глубины для вычисления функции потерь.

Возвращает

DepthEstimatorOutput или tuple(torch.Tensor)

Объект DepthEstimatorOutput или кортеж torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (CHMv2Config) и входных данных.

Метод forward класса CHMv2ForDepthEstimation переопределяет специальный метод __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 в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

Пример:

>>> from transformers import AutoImageProcessor, CHMv2ForDepthEstimation
>>> import torch
>>> 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())).convert("RGB")

>>> processor = AutoImageProcessor.from_pretrained("facebook/dinov3-vitl16-chmv2-dpt-head")
>>> model = CHMv2ForDepthEstimation.from_pretrained("facebook/dinov3-vitl16-chmv2-dpt-head")

>>> device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
>>> model.to(device)

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

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

>>> # interpolate to original size
>>> post_processed_output = processor.post_process_depth_estimation(
...     outputs, [(image.height, image.width)],
... )
>>> predicted_depth = post_processed_output[0]["predicted_depth"]
Update on GitHub

←BiT Условный DETR→