如何正确解读输出?sapiens2-pointmap-1b-bf16 的 pointmaps 与 scales 返回值详解

原创2026-10-18 11:46:261,412 阅读

如何正确解读输出?sapiens2-pointmap-1b-bf16 的 pointmaps 与 scales 返回值详解

mlx-community/sapiens2-pointmap-1b-bf16 是 Meta Sapiens2 人体感知模型(ICLR 2026)的 MLX bf16 转换版,能够从一张照片逐像素估计 3D 点图(pointmap)。很多新手跑完推理后,面对 pointmaps 和 scales 这两个返回值常常一头雾水:(H, W, 3) 里每个数到底代表什么?scales 为什么只有一个数?这篇指南用最短的篇幅讲清楚它们的含义与正确用法。

🧭 输出全景:一次推理返回什么

按 README.md 中的示例,用 mlx-vlm 加载模型并推理后:

from mlx_vlm import load
from mlx_vlm.models.sapiens2.generate import Sapiens2Predictor, read_image

model, _ = load("mlx-community/sapiens2-pointmap-1b-bf16")
predictor = Sapiens2Predictor(model)
output = predictor.infer(read_image("image.jpg"))
pointmaps, scale = output["pointmaps"], output["scales"]  # (H, W, 3), (1,)

输出是 numpy 数组,核心就两个字段:

字段 shape 含义
pointmaps (H, W, 3) 每个像素对应的 3D 坐标 (X, Y, Z),分辨率与输入图像一致
scales (1,) 整图共用的单一缩放系数(全局尺度)

💡 注意:dense 类任务的输出分辨率与你送入的图片一致,不是某个固定值。

🔍 pointmaps 详解:(H, W, 3) 里每个数是什么

pointmaps[row, col] 就是图片中该像素在相机坐标系下的三维位置:

  • 第 0 维 X:水平方向,向右为正;
  • 第 1 维 Y:垂直方向;
  • 第 2 维 Z:深度,沿相机光轴向前,离相机越远值越大。

也就是说,一张 (H, W) 的图片会生成 H × W 个 3D 点,天然形成与图像逐像素对齐的稠密点云。

最常用的用法:取出深度图

depth = pointmaps[..., 2]  # (H, W),即 Z 通道

depth 可以直接当作单目深度估计的结果使用。

⚖️ scales 详解:从"相对点云"到真实尺度

单张图像本身无法确定绝对尺寸(照片不知道物体离你 1 米还是 10 米),因此模型先把 3D 点预测在一个相对尺度上,再用 scales 把整张点云整体换算到真实尺度:

metric_points = pointmaps * scale[0]  # 米制点云

两个注意点:

  • scales 是 (1,) 的一维数组,每张图只有一个值,不是逐像素的;
  • 如果只关心相对深度(做可视化、判断前后关系),可以直接用 pointmaps,无需 scale。

🛠 三个常见任务速查

1️⃣ 生成深度热力图

import matplotlib.pyplot as plt

depth = pointmaps[..., 2]
plt.imshow(depth / depth.max(), cmap="magma")
plt.show()

2️⃣ 导出米制 3D 点云

pts = (pointmaps * scale[0]).reshape(-1, 3)  # (N, 3)
np.save("cloud.npy", pts)  # 可用 Open3D / trimesh 查看

3️⃣ 验证输出是否正常

  • pointmaps.shape[:2] 应与输入图尺寸一致;
  • depth 应符合"近小远大"的直觉:前景深度小、背景深度大;
  • scale[0] 通常为正数,量级在 1 附近。

📁 相关文件速览

文件 说明
README.md 模型简介与 mlx-vlm 调用示例
config.json 模型结构:40 层 ViT 主干 + 解码头(conv_pointmap 与 scale 分支)
preprocessor_config.json 预处理参数:像素 rescale 与 ImageNet 归一化
model.safetensors bf16 权重(约 3.26 GB,比 float32 原版小一半)
model.safetensors.index.json 556 个张量的权重索引

从 config.json 可以看到架构名为 Sapiens2ForPointmapEstimation:主干是 40 层、hidden_size 1536 的 ViT(RoPE + GQA 注意力);解码头中 decode_head.conv_pointmap 输出 XYZ 点图,decode_head.scale_conv_layers 与 scale_final_layer 输出全局尺度——这正是 pointmaps 与 scales 两个返回值的来源。

❓ 新手最常踩的 3 个坑

  1. 把 scales 当成逐像素值:它只有 1 个数、整图共用,写成 scales[row, col] 会直接报错;
  2. 忘记乘 scale 就当真实距离用:相对点云的绝对数值没有物理意义,需要米制距离时务必 pointmaps * scale[0];
  3. 以为输出是固定 1024×768:dense 任务输出与输入分辨率一致,1024×768 只是模型内部的 image_size 配置,不代表输出尺寸。

一句话总结:pointmaps 是相机坐标系下逐像素的 XYZ 点云(Z 通道即深度),scales 是把点云换算到真实尺度的全局系数;pointmaps[..., 2] 得深度图,pointmaps * scales[0] 得米制点云。

登录后查看全文
sapiens2-pointmap-1b-bf16