Transformers documentation
CHMv2
このモデルは2026年3月6日にHF papersで公開され、2026年3月11日にHugging Face Transformersに貢献されました。
CHMv2
概要
Canopy Height Maps v2 (CHMv2) モデルは、CHMv2: Improvements in Global Canopy Height Mapping using DINOv3 で提案されました。2024年に公開したオリジナルの高解像度樹冠高マップを基盤とし、Metaの自己教師ありビジョンモデルであるDINOv3を活用することで、CHMv2は精度、詳細度、およびグローバルな一貫性において大幅な改善を実現しています。
論文の抄録は以下の通りです。
正確な樹冠高情報（Canopy Height）は、森林炭素の定量化、復元および劣化の監視、生息地構造の評価に不可欠ですが、航空レーザー走査（ALS）による高忠実度の測定値は世界的に偏ってしか利用できません。本稿では、DINOv3を基盤とした深度推定モデルを用い、ALSの樹冠高モデル（CHM）に対して学習させたことで得られる、全球規模のメートル解像度の樹冠高マップCHMv2を提示します。既存の製品と比較して、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
class 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' )
パラメータ
- 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ステージの出力チャネルサイズです。 - fusion_hidden_size (
int、任意、デフォルトは 256) — 融合前のチャネル数です。 - head_hidden_size (
int、任意、デフォルトは 128) — 深度推定ヘッドの隠れ層のチャネル数です。 - number_output_channels (
int、任意、デフォルトは 256) — CHMv2 ヘッドの出力チャネル数（深度ビン数）。 - readout_type (
str、任意、デフォルトは"project") — 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"]のいずれかです。
This is the configuration class to store the configuration of a Chmv2Model. It is used to instantiate a Chmv2 model according to the specified arguments, defining the model architecture. Instantiating a configuration with the defaults will yield a similar configuration to that of the facebook/dinov3-vitl16-chmv2-dpt-head
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
CHMv2ImageProcessor
class transformers.CHMv2ImageProcessor
< source >( **kwargs: *<class 'transformers.models.chmv2.image_processing_chmv2.CHMv2ImageProcessorKwargs'> )
パラメータ
- do_convert_rgb (
bool、kwargs、任意) — 画像を RGB に変換するかどうかを指定します。 - do_resize (
bool、kwargs、任意、デフォルトはFalse) — 画像をリサイズするかどうかを指定します。 - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, デフォルトは{'height' -- 384, 'width': 384}): モデルへの最大入力サイズを指定します。 - default_to_square (
bool、kwargs、任意、デフォルトは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、任意、デフォルトはTrue) — 画像をリスケールするかどうかを指定します。 - rescale_factor (
float、kwargs、任意、デフォルト値は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、任意) — サポートされているのはChannelDimension.FIRSTのみです。slow processors との互換性のために追加されました。 - 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、任意) — サイズごとに画像をグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうか。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている経験則に基づいています。 - image_seq_length (
int、kwargs、任意) — 入力内の各画像に使用される画像トークンの数です。 後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。 - ensure_multiple_of (
int、kwargs、optional、デフォルト値は 1) —do_resizeがTrueの場合、画像はこの値の倍数となるサイズにリサイズされます。preprocess内のensure_multiple_ofによって上書きできます。 - size_divisor (
int, kwargs、デフォルトは16) — 高さと幅の両方が割り切れることを保証するためのサイズです。 - keep_aspect_ratio (
bool、kwargs、任意、デフォルトはFalse) —Trueの場合、アスペクト比を維持したまま、画像を可能な限り大きなサイズにリサイズします。preprocess内のkeep_aspect_ratioによって上書きできます。 - do_reduce_labels (
bool、kwargs、optional、デフォルトはself.do_reduce_labels) — セグメンテーションマップのすべてのラベル値を 1 減らすかどうか。通常、0 が背景に使用され、かつ背景自体がデータセットのすべてのクラスに含まれていないデータセット（例: ADE20k）で使用されます。背景ラベルは 255 に置き換えられます。
CHMv2ImageProcessorの画像プロセッサを構築します。
preprocess
< 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
パラメータ
- 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、任意) — 画像を RGB に変換するかどうかを指定します。 - do_resize (
bool、kwargs、optional) — 画像をリサイズするかどうか。 - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — モデルへの最大入力次元を記述します。 - default_to_square (
bool、kwargs、任意) — サイズが整数の場合、リサイズ時に正方形の画像をデフォルトとするかどうか。 - 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、任意) —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、任意) — サポートされているのはChannelDimension.FIRSTのみです。slow processors との互換性のために追加されました。 - 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、任意) — サイズごとに画像をグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうか。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている経験則に基づいています。 - image_seq_length (
int、kwargs、任意) — 入力内の各画像に使用される画像トークンの数です。 後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。 - ensure_multiple_of (
int、kwargs、optional、デフォルト値は 1) —do_resizeがTrueの場合、画像はこの値の倍数となるサイズにリサイズされます。preprocess内のensure_multiple_ofによって上書きできます。 - size_divisor (
int, kwargs) — 高さと幅の両方が割り切れることを保証するためのサイズです。 - keep_aspect_ratio (
bool、kwargs、任意、デフォルトはFalse) —Trueの場合、アスペクト比を維持したまま、画像を可能な限り大きなサイズにリサイズします。preprocess内のkeep_aspect_ratioによって上書きできます。 - 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]、省略可) — 初期化時に PyTorch/Numpy の Tensor 内の整数リストを変換するために、ここで tensor_type を指定できます。
post_process_depth_estimation
< source >( outputs: DepthEstimatorOutputtarget_sizes: transformers.utils.generic.TensorType | list[tuple[int, int]] | None = None ) → List[Dict[str, TensorType]]
DepthEstimatorOutputの生出力を、最終的な深度予測および深度PIL画像に変換します。
PyTorchのみサポートしています。
CHMv2ForDepthEstimation
クラス transformers.CHMv2ForDepthEstimation
< source >( config: CHMv2Config )
パラメータ
- config (CHMv2Config) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
CHMv2 モデルの上部に深度推定ヘッド（畳み込み層で構成）を備えた構成。例えば、樹冠高さの推定に使用します。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
forward
< source >( pixel_values: FloatTensorlabels: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → DepthEstimatorOutput or tuple(torch.FloatTensor)
パラメータ
- pixel_values (
torch.FloatTensor、shape(batch_size, num_channels, image_size, image_size)) — 入力画像に対応するテンソルです。ピクセル値は CHMv2ImageProcessor を使用して取得できます。詳細は CHMv2ImageProcessor.call() を参照してください（processor_classは画像の処理に CHMv2ImageProcessor を使用します）。 - labels (
torch.LongTensor、形状(batch_size, height, width)、任意) — 損失の計算に使用する正解の深度推定マップです。
戻り値
DepthEstimatorOutput または tuple(torch.FloatTensor)
torch.FloatTensor のタプル、または return_dict=False が渡された場合、または config.return_dict=False の場合は torch.FloatTensor のタプル、それ以外の場合は DepthEstimatorOutput を返します。構成（CHMv2Config）と入力に応じて、さまざまな要素が含まれます。
CHMv2ForDepthEstimationのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
loss (
torch.FloatTensor、shape(1,)、optional、labelsが指定された場合に返されます) — 分類損失（config.num_labels==1 の場合は回帰損失）。predicted_depth (
torch.FloatTensor、形状(batch_size, height, width)) — 各ピクセルの予測深度。hidden_states (
tuple(torch.FloatTensor)、optional、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返される) —torch.FloatTensorのタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は(batch_size, num_channels, height, width)です。各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返されます)—torch.FloatTensorのタプル（各レイヤーごとに1つ）、形状は(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"]