如何正确解读输出?sapiens2-pointmap-1b-bf16 的 pointmaps 与 scales 返回值详解
如何正确解读输出?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 个坑
- 把 scales 当成逐像素值:它只有 1 个数、整图共用,写成
scales[row, col]会直接报错; - 忘记乘 scale 就当真实距离用:相对点云的绝对数值没有物理意义,需要米制距离时务必
pointmaps * scale[0]; - 以为输出是固定 1024×768:dense 任务输出与输入分辨率一致,
1024×768只是模型内部的image_size配置,不代表输出尺寸。
一句话总结:pointmaps 是相机坐标系下逐像素的 XYZ 点云(Z 通道即深度),scales 是把点云换算到真实尺度的全局系数;pointmaps[..., 2] 得深度图,pointmaps * scales[0] 得米制点云。