使用 Transformers 与 CHMv2 进行全球树冠高度制图基于 DINOv3 的深度估计模型实战指南【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformersCHMv2Canopy Height Maps v2是 Meta 于 2026 年发布的新一代全球树冠高度制图模型它复用 DINOv3 自监督视觉骨干网络并结合 DPT 风格的分层特征融合与深度估计头从高分辨率光学卫星影像中逐像素预测植被冠层高度。本指南以 docs/source/en/model_doc/chmv2.md 为骨架结合本仓库 src/transformers/models/chmv2 下的配置、图像处理与建模源码完整讲解 CHMv2 的原理、架构、推理用法与配置参数读完即可用几行代码在自己的遥感影像上产出米级分辨率的冠层高度图。模型背景从 2024 年首版到 DINOv3 驱动的新一代CHMv2 承接了 Meta 于 2024 年公开发布的全球高分辨率树冠高度图Canopy Height Maps工作其技术路线是把高分辨率光学卫星影像输入一个建立在DINOv3Meta 自监督视觉模型之上的深度估计模型并以机载激光扫描ALS测得的树冠高度模型CHM作为训练监督信号最终输出覆盖全球的米级分辨率冠层高度图。相比既有产品CHMv2 论文摘要所宣称的核心改进包括精度显著提升、在高大森林区域偏差更小、能更好地保留林冠边缘与林隙等细粒度结构。这些收益来自更大规模的地理多样性训练数据、自动化的数据清洗与配准以及对树冠高度分布量身定制的损失函数与数据采样策略。模型于 2026-03-06 在相关论文平台公开发表并于 2026-03-11 合入 Hugging Face Transformers即当前仓库。模型与处理器使用 Meta 与 Hugging Face 共同版权代码以 modular_chmv2.py 为唯一事实来源自动生成configuration_chmv2.py、image_processing_chmv2.py、modeling_chmv2.py均标注为不可手工编辑的生成文件。已公开的官方检查点本仓库文档示例与集成测试引用了官方检查点facebook/dinov3-vitl16-chmv2-dpt-head。从命名可读出三层信息vitl16表示 backbone 为 DINOv3 ViT-Large 16 像素 patch 版本chmv2表示使用 CHMv2 的训练配置dpt-head表示预测头采用 DPT 风格结构。集成测试对该检查点输出了可复现的数值断言见 tests/models/chmv2/test_modeling_chmv2.py。快速上手单张影像的冠层高度推理文档给出的标准推理流程如下原样保留并在注释中补充要点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_mapauto ) image Image.open(image.tif) inputs processor(imagesimage, return_tensorspt).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]代码的机制拆解如下自动类路由chmv2模型类型已在自动映射中注册——auto_mappings.py 将CHMv2ImageProcessor注册到图像处理器映射、modeling_auto.py 将CHMv2ForDepthEstimation注册到深度估计模型映射因此这里可以用AutoImageProcessor与AutoModelForDepthEstimation直接加载无需显式 import 具体类。影像格式示例直接打开image.tif。树冠高度制图的业务输入通常是多光谱或 RGB 卫星影像的 GeoTIFF 切片PIL 打开后即作为普通 RGB 图输入处理器后续如需地理配准可在后处理阶段自行把像素坐标映射回投影坐标。device_mapauto把模型自动分配到可用设备GPU/多卡/CPU 回退随后inputs.to(model.device)保证输入与参数同设备。预测后处理post_process_depth_estimation(outputs, target_sizes[(height, width)])用双线性插值把模型原生分辨率输出缩放到输入影像原始尺寸返回predicted_depth张量其中每个像素值即该处预测的冠层高度单位为米见下文深度箱设计。若希望保留模型原生分辨率而不回缩到原图尺寸省略target_sizes即可这与集成测试中的行为一致。集成测试对输出形状的验证慢速集成测试 tests/models/chmv2/test_modeling_chmv2.py 以一张官方示例 TIFF 为输入加载后转 RGB断言了如下事实可作为自测基线原生推理输出predicted_depth形状为[1, 448, 448]即分辨率与输入预处理后的张量一致而非384×384——因为推理尺寸由预处理填充结果决定输出前三行前三列与期望切片[[0.1028, 0.0562, 0.0575], [0.4136, 0.5476, 0.4333], [1.8045, 2.3640, 1.6928]]在atol5e-3, rtol5e-3内一致不经target_sizes的后处理保持448×448传入target_sizes[(原图高, 原图宽)]后则恢复原图分辨率。推理环境约束CHMv2ImageProcessor.post_process_depth_estimation内部通过requires_backends(self, torch)校验 PyTorch 可用性即后处理只支持 PyTorch 后端见 image_processing_chmv2.py。推理前请确保环境安装了torch、transformers与 PIL 兼容的图像栈。架构拆解DINOv3 骨干 DPT 式头CHMv2 没有独立的基础模型无CHMv2Model只有一个带深度估计头的组合模型CHMv2ForDepthEstimation其前向逻辑见 modeling_chmv2.py分为四个阶段DINOv3 骨干提取多尺度特征模型通过load_backbone(config)加载 backbone见 backbone_utils.py 同目录依赖默认配置指向dinov3_vit。骨干在out_indices[6, 12, 18, 24]四层分别取出特征图并与各层 CLS token 一起返回return_class_tokenTrue形成list(zip(feature_maps, cls_tokens))。Reassemble 阶段CHMv2ReassembleStagemodeling_chmv2.py把每层带 CLS 的序列特征重塑回 2D 特征图按readout_type默认project把 CLS token 信息注入每个 patch 位置再由CHMv2ReassembleLayer做 1×1 投影并按reassemble_factors进行上/下采样factor 1用ConvTranspose2d上采样factor 1恒等factor 1用 stride 卷积下采样。RefineNet 式自底向上融合4 个尺度的特征先各自经 3×3 卷积统一到fusion_hidden_size通道默认 256再由CHMv2FeatureFusionLayer自最深尺度开始逐级与更浅尺度残差相加并 2× 双线性上采样逐级恢复高分辨率细节。残差单元CHMv2PreActResidualLayer采用预激活结构ReLU→Conv→ReLU→Conv 后加残差。该设计来自 DPT/DepthAnything 一脉modular_chmv2.py 直接从 dpt 模块复用DPTReassembleLayer、从 depth_anything 复用DepthAnythingPreActResidualLayer。深度头与深度箱解码融合结果经CHMv2UpsampleConvHeadConv3×3 → 2× 双线性上采样 → Conv3×3 → ReLU → Conv1×1输出number_output_channels256个通道即 256 个“深度箱”depth bin的 logits最后由CHMv2FeaturesToDepth把 logits 换算成连续深度值。CHMv2ForDepthEstimation继承的CHMv2PreTrainedModelmodeling_chmv2.py声明了关键能力支持 gradient checkpointing、支持 SDPA / Flash Attention / Flex Attention 多种注意力后端_supports_sdpa/_supports_flash_attn/_supports_flex_attn/_supports_attention_backend均为True主输入名为pixel_values输入模态为图像。权重初始化对 Linear/Conv2d/ConvTranspose2d 使用截断正态分布、偏置置零initializer_range默认 0.02。深度箱策略与“高度即深度”的设计CHMv2FeaturesToDepthmodeling_chmv2.py是 CHMv2 区别于普通单值回归深度模型的算法核心深度箱bins头输出 256 个 bin 的 logits每个 bin 对应一个预定义的深度值min_depth0.001、max_depth96.0单位米界定了可预测范围。这正是论文所述“针对树冠高度分布设计 bin 分布”的落地把测距问题变成对 256 个高度区间的加权聚合。三种 bin 分布策略bins_strategylinear在[min_depth, max_depth]等距取 binlog在对数空间等距再取指数使近处低矮/裸地有更细区分chmv2_mixlog默认_create_mixlog_bins在 linear 与 log 之间按线性衰减权重插值且内部先把max_depth除以 8.0再用_create_outputs_with_mixlog_norm在输出端乘回 8.0——这一缩放实现细节使 bin 在近端对齐线性分辨率更高远端偏向对数。四种归一化策略norm_strategylinearrelu(x) eps(0.1)后按通道归一化为权重softmax直接 softmax 得到权重sigmoidsigmoid 后按通道归一化chmv2_mixlog默认对 logits 先做relu对每个样本取通道最小值做裁剪移位移位上限1e-4、额外偏移1e-8分母用nan_to_num与clamp_min(1e-12)保证数值稳定得到权重后用 bin 加权求和再乘 8.0。任何一条分支最终都用torch.einsum(ikmn,k-imn, ...)做 bin 加权求和产出单通道的连续“深度”此处语义为冠层高度图。另外若某输入只有 1 个 bin则直接relu(x) min_depth。CHMv2Config 配置参数全表CHMv2Config定义于 configuration_chmv2.py的model_type为chmv2并声明了sub_configs {backbone_config: AutoConfig}即 backbone 配置以子配置形式内嵌。各参数含义、默认值与取值范围整理如下参数默认值说明与取值范围backbone_configNone骨干网络的配置dict 或PreTrainedConfig均可当前只支持 DINOv3ViTConfig。为None时按下方默认 kwargs 自动构造patch_size16backbone ViT 的 patch 尺寸模型前向用它计算 patch 网格patch_height/patch_widthreassemble_factors[4, 2, 1, 0.5]Reassemble 各层的上/下采样因子1 上采样1 恒等1 下采样长度须与特征层级数一致post_process_channels[128, 256, 512, 1024]每个 backbone 特征层级经 reassemble 后的输出通道数fusion_hidden_size256融合阶段统一卷积 预激活残差单元的通道数head_hidden_size128深度头隐藏层通道数number_output_channels256CHMv2 头输出通道数即深度箱bin数量readout_typeprojectCLS token 的 readout 方式ignore/add/projectmin_depth0.001深度箱计算的最小深度米max_depth96.0深度箱计算的最大深度米bins_strategychmv2_mixlog深度箱分布策略linear/log/chmv2_mixlognorm_strategychmv2_mixlog深度预测归一化策略linear/softmax/sigmoid/chmv2_mixlog当未显式传入backbone_config时__post_init__经由consolidate_backbone_kwargs_to_config以default_config_typedinov3_vit构造默认骨干配置默认 kwargs 为image_size416、hidden_size1024、intermediate_size4096、num_attention_heads16、num_hidden_layers24即 ViT-Large 规模、num_register_tokens4、key_biasTrue、out_indices[6, 12, 18, 24]、reshape_hidden_statesTrue、apply_layernormTrue、layer_norm_eps1e-6、return_class_tokenTrue。其中num_register_tokens4对应 DINOv3 的 register token 机制return_class_token是 reassemble 阶段 readout 所需的数据前提。这些中间参数同样可以以平铺 kwargs 形式传入CHMv2Config由consolidate_backbone_kwargs_to_config收敛进backbone_config。CHMv2Config采用strict数据类约束并带auto_docstring支持标准用法实例化后可作为CHMv2ForDepthEstimation(configuration)的骨架创建随机初始化模型。CHMv2ImageProcessor面向 DPT 风格推理的图像预处理CHMv2ImageProcessorimage_processing_chmv2.py继承 Torchvision 后端在 modular 定义中继承自DPTImageProcessor类级默认值体现了针对树冠高度模型训练的固定预处理协议归一化统计量image_mean[0.420, 0.411, 0.296]、image_std[0.213, 0.156, 0.143]rescale_factor1/255与 2024 首版 CHM 处理管线保持一致目标尺寸size{height: 384, width: 384}default_to_squareTrue关键标志do_resizeFalse实际不强制缩放到正方形目标、do_padTrue、size_divisor16、ensure_multiple_of16、keep_aspect_ratioTrue。这些标志组合成一条“保宽高比 补边对齐 16”的特殊管线体现在_preprocessimage_processing_chmv2.py中按形状分批 resize借助group_images_by_shape/reorder_images按输入形状分组若需 resizeresize()依据ensure_multiple_of16把新尺寸约束为 16 的倍数并在keep_aspect_ratioTrue时以“改动更小的一边”为基准等比缩放见get_resize_output_image_size融合 rescale normalize像素值乘1/255再用上述均值/方差标准化中心补边pad_image把宽高用中间对称补零扩展到ceil(size/16)*16上下左右均分余数归右侧/下侧。这一步解释了集成测试里输入 384 切块经模型后得到 448×448 分辨率的现象——实际推理张量边长是某个 16 的倍数而输出即该张量分辨率。对后处理post_process_depth_estimation把DepthEstimatorOutput.predicted_depth逐样本地用双线性插值align_cornersTrue缩放到target_sizes指定的(height, width)返回[{predicted_depth: tensor}]形式的列表。另外该类还继承了语义分割后处理接口post_process_semantic_segmentation与可选的do_reduce_labels标签归约逻辑把 0 换成 255 再整体减 1这是为与 DPT/语义分割生态保持接口兼容的产物并非 CHMv2 深度估计主流程的必需部分。模型能力与当前限制务必先读基于源码可确认以下边界条件只支持推理训练未实现CHMv2ForDepthEstimation.forward中一旦传入labels即抛出NotImplementedError(Training is not implemented yet)modeling_chmv2.py。测试套件也显式 skip 了训练相关用例test_training与test_model_get_set_embeddings中相关项被跳过/改写。无独立 base 模型与 token 嵌入CHMv2ForDepthEstimation是唯一模型类get_input_embeddings透传 backbone 的 patch 卷积嵌入是nn.Module而非nn.Embedding因此没有input_embeds这类文本式输入路径。注意力后端支持 SDPA/Flash/Flex Attention 切换FlashAttention 徽标亦出现在模型文档页适配大分辨率影像时可用attn_implementation选择相应后端降低显存。输出语义predicted_depth的“深度”在业务上即冠层高度米量程由min_depth/max_depth0.001–96.0 米界定超出该范围的极端值会被 bin 加权机制压向边界附近解读结果时应结合本地 ALS 样本做标定。从原始权重转换 CHMv2 检查点仓库提供了一站式转换脚本 convert_chmv2_to_hf.py支持把原始训练仓库产出的 head-only 或 “backbone head” 合并检查点转换为 HF 格式并保存其模块级 docstring 给出两种用法# 用法 1head 检查点内含 backbone 权重 python -m transformers.models.chmv2.convert_chmv2_to_hf \ --head_checkpoint_path /path/to/checkpoint.pth \ --pytorch_dump_folder_path /path/to/output \ --model_name chmv2 # 用法 2head 检查点 已有 HF 格式 DINOv3 骨干 python -m transformers.models.chmv2.convert_chmv2_to_hf \ --head_checkpoint_path /path/to/head_checkpoint.pth \ --backbone_repo_id facebook/dinov3-vitl16-pretrain-lvd1689m \ --pytorch_dump_folder_path /path/to/output \ --model_name chmv2命令行还提供--backbone_checkpoint_path独立 DINOv3 backbone 原始权重、--verify_image_path转换后用示例图前向并打印深度 shape/均值/极值、--push_to_hub等选项。转换内部机制可作为理解模型结构映射的窗口头部键名通过正则映射HEAD_ORIGINAL_TO_CONVERTED_KEY_MAPPING把原始reassemble_blocks.projects/resize_layers/batchnorm_layers、fusion_blocks.res_conv_unit{1,2}、conv_depth.head等键翻译到 HF 侧head.reassemble_stage.*、head.fusion_layers.*命名convert_chmv2_to_hf.py这与前面架构剖析中每个子模块一一对应backbone 部分复用 DINOv3 的转换函数split_qkv、convert_old_keys_to_new_keys并过滤掉inv_freq、mask_token等非必要键校验环节用load_state_dict(strictFalse)报告 missing/unexpected 键inv_freq类键允许缺失转换配置硬编码为min_depth0.001、max_depth96.0、bins_strategychmv2_mixlog、norm_strategychmv2_mixlog与官方检查点一致。测试与质量保障模型的正确性由两层测试背书tests/models/chmv2/test_modeling_chmv2.py通用建模测试CHMv2ModelTester用极小配置2 层骨干、16 通道等跑ModelTesterMixin全套通用测试与ConfigTester并断言CHMv2ForDepthEstimation输出的predicted_depth形状恰为(batch, image_size, image_size)pipeline_model_mapping将模型映射到depth-estimationpipeline说明其可直接挂载进 Transformers 的深度估计 pipeline 生态慢速集成测试加载真实检查点与官方 TIFF 样本做数值对齐断言前文已述。若想在本仓库内复现可运行针对该模型目录的测试例如需 GPU/网络并设置RUN_SLOW1以包含集成测试RUN_SLOW1 pytest tests/models/chmv2/test_modeling_chmv2.py -k chmv2小结与实践建议CHMv2 展示了“自监督骨干 面向分布的离散深度箱解码”这一组合在遥感稠密预测任务上的工程化范式。实操要点总结如下官方入口用AutoModelForDepthEstimationAutoImageProcessor加载facebook/dinov3-vitl16-chmv2-dpt-head输入直接读 TIFF/RGB 切块即可无需任何自定义预处理预测结果经post_process_depth_estimation(outputs, target_sizes[(h, w)])还原到原图分辨率像素值即米制冠层高度量程默认 0.001–96 米处理大区域影像时建议按 16 的倍数切块、用device_mapauto并把 batch 控制到显存可承受范围推理分辨率由输入决定示例管线实际以较大边长运行如 448目前模型仅用于推理训练未实现需要微调或自训时应等待后续版本或在 Transformers 之外实现标签监督训练路径想深挖结构细节推荐对照阅读 modeling_chmv2.py架构、configuration_chmv2.py全部默认值、image_processing_chmv2.py预处理管线以及 convert_chmv2_to_hf.py权重命名映射。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Transformers 与 CHMv2 进行全球树冠高度制图：基于 DINOv3 的深度估计模型实战指南
使用 Transformers 与 CHMv2 进行全球树冠高度制图基于 DINOv3 的深度估计模型实战指南【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformersCHMv2Canopy Height Maps v2是 Meta 于 2026 年发布的新一代全球树冠高度制图模型它复用 DINOv3 自监督视觉骨干网络并结合 DPT 风格的分层特征融合与深度估计头从高分辨率光学卫星影像中逐像素预测植被冠层高度。本指南以 docs/source/en/model_doc/chmv2.md 为骨架结合本仓库 src/transformers/models/chmv2 下的配置、图像处理与建模源码完整讲解 CHMv2 的原理、架构、推理用法与配置参数读完即可用几行代码在自己的遥感影像上产出米级分辨率的冠层高度图。模型背景从 2024 年首版到 DINOv3 驱动的新一代CHMv2 承接了 Meta 于 2024 年公开发布的全球高分辨率树冠高度图Canopy Height Maps工作其技术路线是把高分辨率光学卫星影像输入一个建立在DINOv3Meta 自监督视觉模型之上的深度估计模型并以机载激光扫描ALS测得的树冠高度模型CHM作为训练监督信号最终输出覆盖全球的米级分辨率冠层高度图。相比既有产品CHMv2 论文摘要所宣称的核心改进包括精度显著提升、在高大森林区域偏差更小、能更好地保留林冠边缘与林隙等细粒度结构。这些收益来自更大规模的地理多样性训练数据、自动化的数据清洗与配准以及对树冠高度分布量身定制的损失函数与数据采样策略。模型于 2026-03-06 在相关论文平台公开发表并于 2026-03-11 合入 Hugging Face Transformers即当前仓库。模型与处理器使用 Meta 与 Hugging Face 共同版权代码以 modular_chmv2.py 为唯一事实来源自动生成configuration_chmv2.py、image_processing_chmv2.py、modeling_chmv2.py均标注为不可手工编辑的生成文件。已公开的官方检查点本仓库文档示例与集成测试引用了官方检查点facebook/dinov3-vitl16-chmv2-dpt-head。从命名可读出三层信息vitl16表示 backbone 为 DINOv3 ViT-Large 16 像素 patch 版本chmv2表示使用 CHMv2 的训练配置dpt-head表示预测头采用 DPT 风格结构。集成测试对该检查点输出了可复现的数值断言见 tests/models/chmv2/test_modeling_chmv2.py。快速上手单张影像的冠层高度推理文档给出的标准推理流程如下原样保留并在注释中补充要点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_mapauto ) image Image.open(image.tif) inputs processor(imagesimage, return_tensorspt).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]代码的机制拆解如下自动类路由chmv2模型类型已在自动映射中注册——auto_mappings.py 将CHMv2ImageProcessor注册到图像处理器映射、modeling_auto.py 将CHMv2ForDepthEstimation注册到深度估计模型映射因此这里可以用AutoImageProcessor与AutoModelForDepthEstimation直接加载无需显式 import 具体类。影像格式示例直接打开image.tif。树冠高度制图的业务输入通常是多光谱或 RGB 卫星影像的 GeoTIFF 切片PIL 打开后即作为普通 RGB 图输入处理器后续如需地理配准可在后处理阶段自行把像素坐标映射回投影坐标。device_mapauto把模型自动分配到可用设备GPU/多卡/CPU 回退随后inputs.to(model.device)保证输入与参数同设备。预测后处理post_process_depth_estimation(outputs, target_sizes[(height, width)])用双线性插值把模型原生分辨率输出缩放到输入影像原始尺寸返回predicted_depth张量其中每个像素值即该处预测的冠层高度单位为米见下文深度箱设计。若希望保留模型原生分辨率而不回缩到原图尺寸省略target_sizes即可这与集成测试中的行为一致。集成测试对输出形状的验证慢速集成测试 tests/models/chmv2/test_modeling_chmv2.py 以一张官方示例 TIFF 为输入加载后转 RGB断言了如下事实可作为自测基线原生推理输出predicted_depth形状为[1, 448, 448]即分辨率与输入预处理后的张量一致而非384×384——因为推理尺寸由预处理填充结果决定输出前三行前三列与期望切片[[0.1028, 0.0562, 0.0575], [0.4136, 0.5476, 0.4333], [1.8045, 2.3640, 1.6928]]在atol5e-3, rtol5e-3内一致不经target_sizes的后处理保持448×448传入target_sizes[(原图高, 原图宽)]后则恢复原图分辨率。推理环境约束CHMv2ImageProcessor.post_process_depth_estimation内部通过requires_backends(self, torch)校验 PyTorch 可用性即后处理只支持 PyTorch 后端见 image_processing_chmv2.py。推理前请确保环境安装了torch、transformers与 PIL 兼容的图像栈。架构拆解DINOv3 骨干 DPT 式头CHMv2 没有独立的基础模型无CHMv2Model只有一个带深度估计头的组合模型CHMv2ForDepthEstimation其前向逻辑见 modeling_chmv2.py分为四个阶段DINOv3 骨干提取多尺度特征模型通过load_backbone(config)加载 backbone见 backbone_utils.py 同目录依赖默认配置指向dinov3_vit。骨干在out_indices[6, 12, 18, 24]四层分别取出特征图并与各层 CLS token 一起返回return_class_tokenTrue形成list(zip(feature_maps, cls_tokens))。Reassemble 阶段CHMv2ReassembleStagemodeling_chmv2.py把每层带 CLS 的序列特征重塑回 2D 特征图按readout_type默认project把 CLS token 信息注入每个 patch 位置再由CHMv2ReassembleLayer做 1×1 投影并按reassemble_factors进行上/下采样factor 1用ConvTranspose2d上采样factor 1恒等factor 1用 stride 卷积下采样。RefineNet 式自底向上融合4 个尺度的特征先各自经 3×3 卷积统一到fusion_hidden_size通道默认 256再由CHMv2FeatureFusionLayer自最深尺度开始逐级与更浅尺度残差相加并 2× 双线性上采样逐级恢复高分辨率细节。残差单元CHMv2PreActResidualLayer采用预激活结构ReLU→Conv→ReLU→Conv 后加残差。该设计来自 DPT/DepthAnything 一脉modular_chmv2.py 直接从 dpt 模块复用DPTReassembleLayer、从 depth_anything 复用DepthAnythingPreActResidualLayer。深度头与深度箱解码融合结果经CHMv2UpsampleConvHeadConv3×3 → 2× 双线性上采样 → Conv3×3 → ReLU → Conv1×1输出number_output_channels256个通道即 256 个“深度箱”depth bin的 logits最后由CHMv2FeaturesToDepth把 logits 换算成连续深度值。CHMv2ForDepthEstimation继承的CHMv2PreTrainedModelmodeling_chmv2.py声明了关键能力支持 gradient checkpointing、支持 SDPA / Flash Attention / Flex Attention 多种注意力后端_supports_sdpa/_supports_flash_attn/_supports_flex_attn/_supports_attention_backend均为True主输入名为pixel_values输入模态为图像。权重初始化对 Linear/Conv2d/ConvTranspose2d 使用截断正态分布、偏置置零initializer_range默认 0.02。深度箱策略与“高度即深度”的设计CHMv2FeaturesToDepthmodeling_chmv2.py是 CHMv2 区别于普通单值回归深度模型的算法核心深度箱bins头输出 256 个 bin 的 logits每个 bin 对应一个预定义的深度值min_depth0.001、max_depth96.0单位米界定了可预测范围。这正是论文所述“针对树冠高度分布设计 bin 分布”的落地把测距问题变成对 256 个高度区间的加权聚合。三种 bin 分布策略bins_strategylinear在[min_depth, max_depth]等距取 binlog在对数空间等距再取指数使近处低矮/裸地有更细区分chmv2_mixlog默认_create_mixlog_bins在 linear 与 log 之间按线性衰减权重插值且内部先把max_depth除以 8.0再用_create_outputs_with_mixlog_norm在输出端乘回 8.0——这一缩放实现细节使 bin 在近端对齐线性分辨率更高远端偏向对数。四种归一化策略norm_strategylinearrelu(x) eps(0.1)后按通道归一化为权重softmax直接 softmax 得到权重sigmoidsigmoid 后按通道归一化chmv2_mixlog默认对 logits 先做relu对每个样本取通道最小值做裁剪移位移位上限1e-4、额外偏移1e-8分母用nan_to_num与clamp_min(1e-12)保证数值稳定得到权重后用 bin 加权求和再乘 8.0。任何一条分支最终都用torch.einsum(ikmn,k-imn, ...)做 bin 加权求和产出单通道的连续“深度”此处语义为冠层高度图。另外若某输入只有 1 个 bin则直接relu(x) min_depth。CHMv2Config 配置参数全表CHMv2Config定义于 configuration_chmv2.py的model_type为chmv2并声明了sub_configs {backbone_config: AutoConfig}即 backbone 配置以子配置形式内嵌。各参数含义、默认值与取值范围整理如下参数默认值说明与取值范围backbone_configNone骨干网络的配置dict 或PreTrainedConfig均可当前只支持 DINOv3ViTConfig。为None时按下方默认 kwargs 自动构造patch_size16backbone ViT 的 patch 尺寸模型前向用它计算 patch 网格patch_height/patch_widthreassemble_factors[4, 2, 1, 0.5]Reassemble 各层的上/下采样因子1 上采样1 恒等1 下采样长度须与特征层级数一致post_process_channels[128, 256, 512, 1024]每个 backbone 特征层级经 reassemble 后的输出通道数fusion_hidden_size256融合阶段统一卷积 预激活残差单元的通道数head_hidden_size128深度头隐藏层通道数number_output_channels256CHMv2 头输出通道数即深度箱bin数量readout_typeprojectCLS token 的 readout 方式ignore/add/projectmin_depth0.001深度箱计算的最小深度米max_depth96.0深度箱计算的最大深度米bins_strategychmv2_mixlog深度箱分布策略linear/log/chmv2_mixlognorm_strategychmv2_mixlog深度预测归一化策略linear/softmax/sigmoid/chmv2_mixlog当未显式传入backbone_config时__post_init__经由consolidate_backbone_kwargs_to_config以default_config_typedinov3_vit构造默认骨干配置默认 kwargs 为image_size416、hidden_size1024、intermediate_size4096、num_attention_heads16、num_hidden_layers24即 ViT-Large 规模、num_register_tokens4、key_biasTrue、out_indices[6, 12, 18, 24]、reshape_hidden_statesTrue、apply_layernormTrue、layer_norm_eps1e-6、return_class_tokenTrue。其中num_register_tokens4对应 DINOv3 的 register token 机制return_class_token是 reassemble 阶段 readout 所需的数据前提。这些中间参数同样可以以平铺 kwargs 形式传入CHMv2Config由consolidate_backbone_kwargs_to_config收敛进backbone_config。CHMv2Config采用strict数据类约束并带auto_docstring支持标准用法实例化后可作为CHMv2ForDepthEstimation(configuration)的骨架创建随机初始化模型。CHMv2ImageProcessor面向 DPT 风格推理的图像预处理CHMv2ImageProcessorimage_processing_chmv2.py继承 Torchvision 后端在 modular 定义中继承自DPTImageProcessor类级默认值体现了针对树冠高度模型训练的固定预处理协议归一化统计量image_mean[0.420, 0.411, 0.296]、image_std[0.213, 0.156, 0.143]rescale_factor1/255与 2024 首版 CHM 处理管线保持一致目标尺寸size{height: 384, width: 384}default_to_squareTrue关键标志do_resizeFalse实际不强制缩放到正方形目标、do_padTrue、size_divisor16、ensure_multiple_of16、keep_aspect_ratioTrue。这些标志组合成一条“保宽高比 补边对齐 16”的特殊管线体现在_preprocessimage_processing_chmv2.py中按形状分批 resize借助group_images_by_shape/reorder_images按输入形状分组若需 resizeresize()依据ensure_multiple_of16把新尺寸约束为 16 的倍数并在keep_aspect_ratioTrue时以“改动更小的一边”为基准等比缩放见get_resize_output_image_size融合 rescale normalize像素值乘1/255再用上述均值/方差标准化中心补边pad_image把宽高用中间对称补零扩展到ceil(size/16)*16上下左右均分余数归右侧/下侧。这一步解释了集成测试里输入 384 切块经模型后得到 448×448 分辨率的现象——实际推理张量边长是某个 16 的倍数而输出即该张量分辨率。对后处理post_process_depth_estimation把DepthEstimatorOutput.predicted_depth逐样本地用双线性插值align_cornersTrue缩放到target_sizes指定的(height, width)返回[{predicted_depth: tensor}]形式的列表。另外该类还继承了语义分割后处理接口post_process_semantic_segmentation与可选的do_reduce_labels标签归约逻辑把 0 换成 255 再整体减 1这是为与 DPT/语义分割生态保持接口兼容的产物并非 CHMv2 深度估计主流程的必需部分。模型能力与当前限制务必先读基于源码可确认以下边界条件只支持推理训练未实现CHMv2ForDepthEstimation.forward中一旦传入labels即抛出NotImplementedError(Training is not implemented yet)modeling_chmv2.py。测试套件也显式 skip 了训练相关用例test_training与test_model_get_set_embeddings中相关项被跳过/改写。无独立 base 模型与 token 嵌入CHMv2ForDepthEstimation是唯一模型类get_input_embeddings透传 backbone 的 patch 卷积嵌入是nn.Module而非nn.Embedding因此没有input_embeds这类文本式输入路径。注意力后端支持 SDPA/Flash/Flex Attention 切换FlashAttention 徽标亦出现在模型文档页适配大分辨率影像时可用attn_implementation选择相应后端降低显存。输出语义predicted_depth的“深度”在业务上即冠层高度米量程由min_depth/max_depth0.001–96.0 米界定超出该范围的极端值会被 bin 加权机制压向边界附近解读结果时应结合本地 ALS 样本做标定。从原始权重转换 CHMv2 检查点仓库提供了一站式转换脚本 convert_chmv2_to_hf.py支持把原始训练仓库产出的 head-only 或 “backbone head” 合并检查点转换为 HF 格式并保存其模块级 docstring 给出两种用法# 用法 1head 检查点内含 backbone 权重 python -m transformers.models.chmv2.convert_chmv2_to_hf \ --head_checkpoint_path /path/to/checkpoint.pth \ --pytorch_dump_folder_path /path/to/output \ --model_name chmv2 # 用法 2head 检查点 已有 HF 格式 DINOv3 骨干 python -m transformers.models.chmv2.convert_chmv2_to_hf \ --head_checkpoint_path /path/to/head_checkpoint.pth \ --backbone_repo_id facebook/dinov3-vitl16-pretrain-lvd1689m \ --pytorch_dump_folder_path /path/to/output \ --model_name chmv2命令行还提供--backbone_checkpoint_path独立 DINOv3 backbone 原始权重、--verify_image_path转换后用示例图前向并打印深度 shape/均值/极值、--push_to_hub等选项。转换内部机制可作为理解模型结构映射的窗口头部键名通过正则映射HEAD_ORIGINAL_TO_CONVERTED_KEY_MAPPING把原始reassemble_blocks.projects/resize_layers/batchnorm_layers、fusion_blocks.res_conv_unit{1,2}、conv_depth.head等键翻译到 HF 侧head.reassemble_stage.*、head.fusion_layers.*命名convert_chmv2_to_hf.py这与前面架构剖析中每个子模块一一对应backbone 部分复用 DINOv3 的转换函数split_qkv、convert_old_keys_to_new_keys并过滤掉inv_freq、mask_token等非必要键校验环节用load_state_dict(strictFalse)报告 missing/unexpected 键inv_freq类键允许缺失转换配置硬编码为min_depth0.001、max_depth96.0、bins_strategychmv2_mixlog、norm_strategychmv2_mixlog与官方检查点一致。测试与质量保障模型的正确性由两层测试背书tests/models/chmv2/test_modeling_chmv2.py通用建模测试CHMv2ModelTester用极小配置2 层骨干、16 通道等跑ModelTesterMixin全套通用测试与ConfigTester并断言CHMv2ForDepthEstimation输出的predicted_depth形状恰为(batch, image_size, image_size)pipeline_model_mapping将模型映射到depth-estimationpipeline说明其可直接挂载进 Transformers 的深度估计 pipeline 生态慢速集成测试加载真实检查点与官方 TIFF 样本做数值对齐断言前文已述。若想在本仓库内复现可运行针对该模型目录的测试例如需 GPU/网络并设置RUN_SLOW1以包含集成测试RUN_SLOW1 pytest tests/models/chmv2/test_modeling_chmv2.py -k chmv2小结与实践建议CHMv2 展示了“自监督骨干 面向分布的离散深度箱解码”这一组合在遥感稠密预测任务上的工程化范式。实操要点总结如下官方入口用AutoModelForDepthEstimationAutoImageProcessor加载facebook/dinov3-vitl16-chmv2-dpt-head输入直接读 TIFF/RGB 切块即可无需任何自定义预处理预测结果经post_process_depth_estimation(outputs, target_sizes[(h, w)])还原到原图分辨率像素值即米制冠层高度量程默认 0.001–96 米处理大区域影像时建议按 16 的倍数切块、用device_mapauto并把 batch 控制到显存可承受范围推理分辨率由输入决定示例管线实际以较大边长运行如 448目前模型仅用于推理训练未实现需要微调或自训时应等待后续版本或在 Transformers 之外实现标签监督训练路径想深挖结构细节推荐对照阅读 modeling_chmv2.py架构、configuration_chmv2.py全部默认值、image_processing_chmv2.py预处理管线以及 convert_chmv2_to_hf.py权重命名映射。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考