Transformers documentation
CHMv2
Ce modèle a été publié dans HF papers le 2026-03-06 et contribué à Hugging Face Transformers le 2026-03-11.
CHMv2
Aperçu
Le modèle Canopy Height Maps v2 (CHMv2) a été proposé dans CHMv2: Improvements in Global Canopy Height Mapping using DINOv3. En s’appuyant sur nos cartes de hauteur de canopée haute résolution d’origine publiées en 2024, CHMv2 apporte des améliorations substantielles en termes de précision, de détail et de cohérence mondiale grâce à l’utilisation de DINOv3, le modèle de vision auto-supervisé de Meta.
Vous trouverez plus d’informations ici, et le code original ici.
L'abstract de l'article est le suivant :
Des informations précises sur la hauteur de la canopée sont essentielles pour quantifier le carbone forestier, surveiller la restauration et la dégradation, et évaluer la structure des habitats, mais les mesures haute fidélité issues du balayage laser aéroporté (ALS) restent inégalement disponibles à l’échelle mondiale. Nous présentons ici CHMv2, une carte mondiale de la hauteur de la canopée à résolution métrique, dérivée d’images satellites optiques haute résolution à l’aide d’un modèle d’estimation de profondeur construit sur DINOv3 et entraîné sur des modèles de hauteur de canopée ALS. Par rapport aux produits existants, CHMv2 améliore considérablement la précision, réduit le biais dans les forêts hautes et préserve mieux la structure à fine échelle, telle que les bords de canopée et les ouvertures. Ces gains sont rendus possibles par une grande expansion des données d’entraînement géographiquement diversifiées, une curation et une enregistrement automatisés des données, ainsi que par une formulation de perte et une stratégie d’échantillonnage des données adaptées aux distributions de hauteur de canopée. Nous validons CHMv2 par rapport à des ensembles de test ALS indépendants et à des dizaines de millions d’observations GEDI et ICESat-2, démontrant des performances cohérentes à travers les principaux biomes forestiers.
Exemples d'utilisation
Exécutez une inférence sur une image avec le code suivant :
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
classe transformers.CHMv2Config
< source >( 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' )
Paramètres
- backbone_config (
Union[dict, "PreTrainedConfig"], facultatif) — La configuration du modèle backbone. Seule DINOv3ViTConfig est actuellement prise en charge. - patch_size (
int, facultatif, par défaut 16) — La taille des patches utilisée par le vision transformer du backbone. - initializer_range (
float, facultatif, par défaut0.02) — L'écart-type de la truncated_normal_initializer utilisé pour initialiser toutes les matrices de poids. - reassemble_factors (
list[float], facultatif, par défaut[4, 2, 1, 0.5]) — Les facteurs de suréchantillonnage/sous-échantillonnage des couches de reassembly. - post_process_channels (
list[int], facultatif, par défaut[128, 256, 512, 1024]) — Les tailles de canaux de sortie de l'étape de réassemblage pour chaque niveau de caractéristique du backbone. - fusion_hidden_size (
int, facultatif, valeur par défaut 256) — Le nombre de canaux avant la fusion. - head_hidden_size (
int, facultatif, par défaut 128) — Le nombre de canaux dans la couche cachée de la tête d’estimation de profondeur. - number_output_channels (
int, facultatif, valeur par défaut 256) — Nombre de canaux de sortie pour la tête CHMv2 (nombre de bins de profondeur). - readout_type (
str, facultatif, par défaut"project") — Type d'opération de lecture pour le jeton CLS. L'un des["ignore", "add", "project"]. - min_depth (
float, facultatif, valeur par défaut 0.001) — Valeur minimale de profondeur pour le calcul des intervalles de profondeur. - max_depth (
float, facultatif, valeur par défaut 96.0) — Valeur maximale de profondeur pour le calcul des intervalles de profondeur. - bins_strategy (
str, facultatif, par défaut"chmv2_mixlog") — La stratégie de distribution des bins de profondeur. L'une des valeurs["linear", "log", "chmv2_mixlog"]. - norm_strategy (
str, facultatif, par défaut"chmv2_mixlog") — La stratégie de normalisation pour la prédiction de la profondeur. L’une des valeurs["linear", "softmax", "sigmoid", "chmv2_mixlog"].
Ceci est la classe de configuration destinée à stocker la configuration d'un Chmv2Model. Elle est utilisée pour instancier un modèle Chmv2 en fonction des arguments spécifiés, définissant ainsi l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de facebook/dinov3-vitl16-chmv2-dpt-head
Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.
CHMv2ImageProcessor
classe transformers.CHMv2ImageProcessor
< source >( **kwargs: *<class 'transformers.models.chmv2.image_processing_chmv2.CHMv2ImageProcessorKwargs'> )
Paramètres
- do_convert_rgb (
bool, kwargs, facultatif) — Indique s'il faut convertir l'image en RGB. - do_resize (
bool, kwargs, facultatif, valeur par défautFalse) — Indique s'il faut redimensionner l'image. - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, par défaut{'height' -- 384, 'width': 384}) : Définit les dimensions d'entrée maximales pour le modèle. - default_to_square (
bool, kwargs, facultatif, valeur par défautTrue) — Indique s'il faut utiliser une image carrée par défaut lors du redimensionnement, si la taille est un entier. - crop_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, par défautNone) — Taille de l'image de sortie après application decenter_crop. - resample (
Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, par défaut3) — Filtre de rééchantillonnage à utiliser lors du redimensionnement de l’image. Il peut s’agir de l’une des valeurs de l’enumPILImageResampling. N’a un effet que sido_resizeest défini surTrue. - do_rescale (
bool, kwargs, facultatif, par défautTrue) — Indique s'il faut rééchelonner l'image. - rescale_factor (
float, kwargs, facultatif, valeur par défaut0.00392156862745098) — Facteur de remise à l'échelle appliqué à l'image sido_rescaleest défini surTrue. - do_normalize (
bool, kwargs, facultatif, valeur par défautTrue) — Indique s'il faut normaliser l'image. - image_mean (
Union[float, list[float], tuple[float, ...]], kwargs, facultatif, valeur par défaut[0.42, 0.411, 0.296]) — Moyenne de l'image à utiliser pour la normalisation. N'a un effet que sido_normalizeest défini surTrue. - image_std (
Union[float, list[float], tuple[float, ...]], kwargs, facultatif, valeur par défaut[0.213, 0.156, 0.143]) — Écart-type de l'image à utiliser pour la normalisation. N'a un effet que sido_normalizeest défini surTrue. - do_pad (
bool, kwargs, facultatif, valeur par défautTrue) — Indique s'il faut appliquer un bourrage (padding) à l'image. Le bourrage est effectué soit jusqu'à la plus grande taille du lot, soit jusqu'à une taille carrée fixe par image. La stratégie de bourrage exacte dépend du modèle. - pad_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — La taille au format{"height": int, "width" int}à laquelle les images doivent être remplies. Elle doit être supérieure à la taille de n'importe quelle image fournie pour la prétraitement. Sipad_sizen'est pas fourni, les images seront remplies jusqu'à la hauteur et la largeur maximales du lot. Appliqué uniquement lorsquedo_pad=True. - do_center_crop (
bool, kwargs, facultatif, valeur par défautNone) — Indique s'il faut effectuer un recadrage centré de l'image. - data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, facultatif) — SeulChannelDimension.FIRSTest pris en charge. Ajouté pour la compatibilité avec les processeurs lents. - input_data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, facultatif) — Le format de la dimension des canaux pour l'image d'entrée. Si non défini, le format de la dimension des canaux est déduit de l'image d'entrée. Peut être l'un des éléments suivants :"channels_first"ouChannelDimension.FIRST: image au format (num_channels, height, width)."channels_last"ouChannelDimension.LAST: image au format (hauteur, largeur, nombre de canaux)."none"ouChannelDimension.NONE: image au format (hauteur, largeur).
- device (
Annotated[Union[str, torch.device, NoneType], None], kwargs) — L’appareil sur lequel traiter les vidéos. Si non défini, l’appareil est déduit des vidéos d’entrée. - return_tensors (
Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Retourne des tenseurs empilés si défini sur'pt', sinon retourne une liste de tenseurs. - disable_grouping (
bool, kwargs, facultatif) — Indique s'il faut désactiver le regroupement des images par taille afin de les traiter individuellement plutôt que par lots. Si la valeur est None, elle est définie sur True si les images sont sur CPU, et sur False dans le cas contraire. Ce choix repose sur des observations empiriques, comme détaillé ici : https://github.com/huggingface/transformers/pull/38157 - image_seq_length (
int, kwargs, facultatif) — Le nombre de jetons d’image à utiliser pour chaque image de l’entrée. Ajouté pour la compatibilité ascendante, mais cela devrait être défini comme un attribut du processeur dans les futurs modèles. - ensure_multiple_of (
int, kwargs, facultatif, valeur par défaut 1) — Sido_resizeestTrue, l’image est redimensionnée à une taille qui est un multiple de cette valeur. Peut être remplacé parensure_multiple_ofdanspreprocess. - size_divisor (
int, kwargs, par défaut16) — La taille par laquelle il faut s'assurer que la hauteur et la largeur sont divisibles. - keep_aspect_ratio (
bool, kwargs, facultatif, valeur par défautFalse) — SiTrue, l'image est redimensionnée à la taille maximale possible tout en préservant le ratio d'aspect. Peut être remplacé parkeep_aspect_ratiodanspreprocess. - do_reduce_labels (
bool, kwargs, facultatif, par défautself.do_reduce_labels) — Indique s'il faut réduire de 1 toutes les valeurs des étiquettes des cartes de segmentation. Utilisé généralement pour les jeux de données où 0 est utilisé pour l'arrière-plan, et où l'arrière-plan lui-même n'est pas inclus dans toutes les classes du jeu de données (par exemple ADE20k). L'étiquette de l'arrière-plan sera remplacée par 255.
Construit un processeur d’images CHMv2ImageProcessor.
prétraiter
< source >( 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
Paramètres
- images (
Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]) — Image à prétraiter. S'attend à une image unique ou à un lot d'images dont les valeurs de pixels vont de 0 à 255. Si vous passez des images dont les valeurs de pixels sont comprises entre 0 et 1, définissezdo_rescale=False. - segmentation_maps (
ImageInput, facultatif) — Les cartes de segmentation à prétraiter. - do_convert_rgb (
bool, kwargs, facultatif) — Indique s'il faut convertir l'image en RGB. - do_resize (
bool, kwargs, facultatif) — Indique s'il faut redimensionner l'image. - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Définit les dimensions maximales des entrées du modèle. - default_to_square (
bool, kwargs, facultatif) — Indique s'il faut par défaut redimensionner l'image en carré si la taille est un entier. - crop_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Taille de l'image de sortie après application decenter_crop. - resample (
Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — Filtre de rééchantillonnage à utiliser lors du redimensionnement de l’image. Il peut s’agir de l’une des valeurs de l’enumPILImageResampling. N’a un effet que sido_resizeest défini surTrue. - do_rescale (
bool, kwargs, facultatif) — Indique s'il faut rééchelonner l'image. - rescale_factor (
float, kwargs, facultatif) — Facteur de remise à l'échelle à appliquer à l'image sido_rescaleest défini surTrue. - do_normalize (
bool, kwargs, facultatif) — Indique s'il faut normaliser l'image. - image_mean (
Union[float, list[float], tuple[float, ...]], kwargs, facultatif) — Moyenne de l'image à utiliser pour la normalisation. N'a un effet que sido_normalizeest défini surTrue. - image_std (
Union[float, list[float], tuple[float, ...]], kwargs, facultatif) — Écart-type de l'image à utiliser pour la normalisation. N'a un effet que sido_normalizeest défini surTrue. - do_pad (
bool, kwargs, facultatif) — Indique s'il faut effectuer un bourrage (padding) de l'image. Le bourrage est effectué soit jusqu'à la plus grande taille du lot, soit jusqu'à une taille carrée fixe par image. La stratégie de bourrage exacte dépend du modèle. - pad_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — La taille au format{"height": int, "width" int}à laquelle les images doivent être remplies. Elle doit être supérieure à la taille de n'importe quelle image fournie pour la prétraitement. Sipad_sizen'est pas fourni, les images seront remplies jusqu'à la hauteur et la largeur maximales du lot. Appliqué uniquement lorsquedo_pad=True. - do_center_crop (
bool, kwargs, facultatif) — Indique s'il faut effectuer un recadrage centré de l'image. - data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, facultatif) — SeulChannelDimension.FIRSTest pris en charge. Ajouté pour la compatibilité avec les processeurs lents. - input_data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, facultatif) — Le format de la dimension des canaux pour l'image d'entrée. Si non défini, le format de la dimension des canaux est déduit de l'image d'entrée. Peut être l'un des éléments suivants :"channels_first"ouChannelDimension.FIRST: image au format (num_channels, height, width)."channels_last"ouChannelDimension.LAST: image au format (hauteur, largeur, nombre de canaux)."none"ouChannelDimension.NONE: image au format (hauteur, largeur).
- device (
Annotated[Union[str, torch.device, NoneType], None], kwargs) — L’appareil sur lequel traiter les vidéos. Si non défini, l’appareil est déduit des vidéos d’entrée. - return_tensors (
Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Retourne des tenseurs empilés si défini sur'pt', sinon retourne une liste de tenseurs. - disable_grouping (
bool, kwargs, facultatif) — Indique s'il faut désactiver le regroupement des images par taille afin de les traiter individuellement plutôt que par lots. Si la valeur est None, elle est définie sur True si les images sont sur CPU, et sur False dans le cas contraire. Ce choix repose sur des observations empiriques, comme détaillé ici : https://github.com/huggingface/transformers/pull/38157 - image_seq_length (
int, kwargs, facultatif) — Le nombre de jetons d’image à utiliser pour chaque image de l’entrée. Ajouté pour la compatibilité ascendante, mais cela devrait être défini comme un attribut du processeur dans les futurs modèles. - ensure_multiple_of (
int, kwargs, facultatif, valeur par défaut 1) — Sido_resizeestTrue, l’image est redimensionnée à une taille qui est un multiple de cette valeur. Peut être remplacé parensure_multiple_ofdanspreprocess. - size_divisor (
int, kwargs) — La taille par laquelle il faut s'assurer que la hauteur et la largeur sont divisibles. - keep_aspect_ratio (
bool, kwargs, facultatif, valeur par défautFalse) — SiTrue, l'image est redimensionnée à la taille maximale possible tout en préservant le ratio d'aspect. Peut être remplacé parkeep_aspect_ratiodanspreprocess. - do_reduce_labels (
bool, kwargs, facultatif, par défautself.do_reduce_labels) — Indique s'il faut réduire de 1 toutes les valeurs des étiquettes des cartes de segmentation. Utilisé généralement pour les jeux de données où 0 est utilisé pour l'arrière-plan, et où l'arrière-plan lui-même n'est pas inclus dans toutes les classes du jeu de données (par exemple ADE20k). L'étiquette de l'arrière-plan sera remplacée par 255.
Retourne
~image_processing_base.BatchFeature
- data (
dict) — Dictionnaire de listes/tableaux/tenseurs renvoyé par la méthode call (« pixel_values », etc.). - tensor_type (
Union[None, str, TensorType], facultatif) — Vous pouvez spécifier un tensor_type ici pour convertir les listes d'entiers en tenseurs PyTorch/Numpy lors de l'initialisation.
post_process_depth_estimation
< source >( outputs: DepthEstimatorOutputtarget_sizes: transformers.utils.generic.TensorType | list[tuple[int, int]] | None = None ) → List[Dict[str, TensorType]]
Paramètres
- outputs (
DepthEstimatorOutput) — Sorties brutes du modèle. - target_sizes (
TensorTypeorList[Tuple[int, int]], facultatif) — Tenseur de forme(batch_size, 2)ou liste de tuples (Tuple[int, int]) contenant la taille cible (hauteur, largeur) de chaque image du lot. Si laissé à None, les prédictions ne seront pas redimensionnées.
Retourne
List[Dict[str, TensorType]]
Une liste de dictionnaires de tenseurs représentant les prédictions de profondeur traitées.
Convertit la sortie brute de DepthEstimatorOutput en prédictions de profondeur finales et en images de profondeur PIL.
Prend uniquement en charge PyTorch.
CHMv2ForDepthEstimation
classe transformers.CHMv2ForDepthEstimation
< source >( config: CHMv2Config )
Paramètres
- config (CHMv2Config) — Classe de configuration du modèle contenant tous les paramètres du modèle. L’initialisation à partir d’un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode from_pretrained() pour charger les poids du modèle.
Modèle CHMv2 avec une tête d'estimation de profondeur au sommet (composée de couches convolutives), par exemple pour l'estimation de la hauteur de la canopée.
Ce modèle hérite de PreTrainedModel. Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, la taille des têtes, etc.)
Ce modèle est également une sous-classe de torch.nn.Module de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l'utilisation et le comportement généraux.
forward
< source >( pixel_values: Tensorlabels: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → DepthEstimatorOutput or tuple(torch.Tensor)
Paramètres
- pixel_values (
torch.Tensorde forme(batch_size, num_channels, image_size, image_size)) — Les tenseurs correspondant aux images d’entrée. Les valeurs de pixels peuvent être obtenues à l’aide de CHMv2ImageProcessor. Voir CHMv2ImageProcessor.call() pour plus de détails (processor_classutilise CHMv2ImageProcessor pour le traitement des images). - labels (
torch.LongTensorde forme(batch_size, height, width), facultatif) — Cartes d'estimation de profondeur de référence pour le calcul de la perte.
Retourne
DepthEstimatorOutput ou tuple(torch.Tensor)
Un DepthEstimatorOutput ou un tuple de
torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers
éléments en fonction de la configuration (CHMv2Config) et des entrées.
La méthode forward de CHMv2ForDepthEstimation redéfinit la méthode spéciale __call__.
Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance
Moduleplutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.
loss (
torch.Tensorde forme(1,), facultatif, renvoyé lorsquelabelsest fourni) — Perte de classification (ou de régression si config.num_labels==1).predicted_depth (
torch.Tensorde forme(batch_size, height, width)) — Profondeur prédite pour chaque pixel.hidden_states (
tuple(torch.Tensor), facultatif, renvoyé lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.Tensor(un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme(batch_size, num_channels, height, width).États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.
attentions (
tuple(torch.Tensor), facultatif, renvoyé lorsqueoutput_attentions=Trueest passé ou lorsqueconfig.output_attentions=True) — Tuple detorch.Tensor(un par couche) de forme(batch_size, num_heads, patch_size, sequence_length).Poids des attentions après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.
Exemple :
>>> 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"]