map-anything-fp16 是 Meta MapAnything 度量 3D 重建模型的 MLX float16 移植版，一次前向推理即可输出点云 pts3d、度量深度、相机位姿、内参、置信度、有效掩码共 6 大预测输出。本文逐个拆解每个输出的含义、典型用法和常见坑，帮你在 Apple 设备上快速拿到干净的 3D 重建结果。

map-anything-fp16 是什么？30 秒了解背景

MapAnything（Meta 与 CMU，3DV 2026）是一个前馈式度量 3D 重建模型：输入一张或多张照片（可任选附加内参、深度图、相机位姿），一次前向就能为每个视角同时算出完整的 3D 几何，无需传统多视图立体的迭代优化。

map-anything-fp16 是它的 MLX 社区移植版，专为 Apple Silicon（M 系列芯片）优化：

• ⚖️ 权重仅 2.65 GB（float16），约为 float32 原版的一半，见 model.safetensors
• 内部由 1.13B float16 参数（DINOv2 ViT-g/14 编码器 + 16 层多视图 Transformer）和 95M float32 参数（几何预测头）组成
• 仓库只含权重与元数据，推理代码在 mlx-vlm 中
• 许可证 CC BY-NC 4.0，仅限非商用；商用请选 Apache 2.0 版本mlx-community/map-anything-apache-fp16

6 大预测输出总览：形状与含义一张表看懂

每次推理对每个视角返回一个字典，共 6 个输出（用法示例见 README.md）：

它们由raydirs+depth+pose+confidence+mask+scale这套预测头统一生成（见 config.json），上表就是最终暴露给你的 6 个结果。

pts3d 点云怎么用？3D 重建的"最终答案"

pts3d是每个像素在世界坐标系（第一视角坐标系）下的三维坐标，单位是米——这就是"度量重建"的含义，不需要再猜比例尺。

典型用法：

1. 直接可视化：命令行模式会自动把点云导出成彩色points.ply文件，用 CloudCompare 等工具打开即可（参考 README.md）
2. 与深度互相印证：pts3d 本质是 depth_z 沿相机光线"反投影"的结果
3. 多视角融合：多个视角的 pts3d 天然在同一坐标系下，直接拼接就是完整场景

depth_z 度量深度：米制距离的三种典型用法

depth_z是每个像素到相机的距离（米），由 exp 模式回归保证恒为正（见 config.json）。

• 📱AR 应用：把虚拟物体贴在正确距离处
• 🤖机器人/无人机：实时判断障碍距离
• 🏗️3D 建模：作为高斯泼溅等方法的深度先验

注意：单张图远端区域的深度误差会变大，这时就要请出conf和mask来把关。

conf 置信度怎么用？筛掉不可靠像素的过滤器

conf给每个像素打一个可靠性分数，数值越高，模型对该像素越有信心（exp 激活，见 config.json）。

• 设阈值过滤：低 conf 像素直接丢弃，显著减少"鬼影"和边缘抖动
• 做融合权重：多视角点云融合时按 conf 加权平均，比简单叠加更稳
• 诊断照片质量：整体 conf 偏低，说明照片模糊、过曝或缺乏纹理，先换照片再谈算法

mask 有效掩码：第一步就该做的过滤

mask是"非歧义掩码"，标记哪些像素的预测有效（1 为有效）。反射面、天空、强遮挡区域容易被标记为无效。

✅ 推荐处理顺序：先看 mask 排除无效区域 → 再用 conf 在有效区域内挑可信像素。两步走完，剩下的就是干净的几何结果。

camera_poses 与 intrinsics：相机位姿和内参的作用

• camera_poses（1,4,4）：OpenCV 约定的 cam2world 矩阵，即相机在世界坐标系中的位置与朝向。多视角时用它对齐各视角、回放拍照轨迹
• intrinsics（1,3,3）：相机内参（焦距、主点）。手动把深度图反投影成点云或做透视变换时用得到

💡 妙处在于不依赖外部标定：拍照时没有任何相机参数，模型也会把它们一并预测出来。

快速上手：两条命令拿到全部 6 个预测输出

方式一：Python API（需安装支持 mapanything 的 mlx-vlm）

import mlx.core as mx from mlx_vlm import load model, processor = load("mlx-community/map-anything-fp16") views = processor.load_images("path/to/images") predictions = model.infer(views) # 每个视角一个 dict mx.eval(predictions) pred = predictions[0] pred["pts3d"] # (1, H, W, 3) 度量世界点 pred["depth_z"] # (1, H, W, 1) 度量深度 pred["conf"] # (1, H, W) 置信度

方式二：命令行（自动写出全部输出的predictions.npz+ 彩色points.ply）

MLX_ENABLE_TF32=0 python -m mlx_vlm.models.mapanything.generate \ --model mlx-community/map-anything-fp16 --images path/to/images --output out

两个小贴士：

• 每个视角都可以任选附加内参、深度图、相机位姿，任意组合都行（参考 README.md）
• 图片会被缩放到固定 518 分辨率（如 518×294），见 preprocessor_config.json

实用技巧清单：精度、速度与注意事项

常见问题速答：pts3d 和 depth_z 什么关系？

Q：pts3d 和 depth_z 到底什么关系？同一几何信息的两种表达：depth_z 是"每个像素离相机多远"，pts3d 是把深度沿光线放回世界坐标后的点云。要米制距离用 depth_z，要 3D 场景用 pts3d。

Q：输出的坐标系是哪里？以第一视角的相机坐标系为原点，多视角结果天然在同一坐标系下，无需手动对齐。

Q：怎么判断预测可不可信？三步走：mask 排除无效 → conf 阈值过滤 → 观察深度连续性是否平滑。

总结

map-anything-fp16 的 6 大预测输出各有分工：pts3d给最终点云，depth_z给度量深度，camera_poses与intrinsics补齐相机参数，conf和mask负责质量把关。记住"mask 先过滤、conf 再筛选、pts3d/depth_z 取结果"这条主线，一次前向推理即可在 Apple 设备上快速拿到干净的度量 3D 重建结果。