任意组合深度图、相机位姿与内参：map-anything-apache-fp16 进阶输入配置详解

map-anything-apache-fp16 是 MapAnything（Meta 与 CMU 的度量级前馈式 3D 重建模型）的 float16 MLX 移植版，专为 Apple Silicon 优化。它最灵活的地方在于：每一张输入图像都可以自由搭配相机内参、深度图与相机位姿中的任意组合——只给照片、部分标定，还是全部提供，模型一次前向推理就能输出度量点云、深度图、相机位姿、内参、置信度与有效像素掩码，让你用已有的 SfM / 深度估计 / 标定结果大幅增强 3D 重建质量。

🧭 这个模型能做什么？

📥 三种可选输入逐项详解

1️⃣ 相机内参intrinsics

一个 3×3 的标定矩阵K。如果你手头有现成的标定结果（OpenCV 标定、相机厂商参数等），直接传入即可，模型会利用它约束光线方向，而不是靠网络猜测。

2️⃣ 深度图depth_z

逐像素的度量深度图，与输入图像分辨率一致。来源可以是单目深度估计模型、LiDAR 或深度相机。给模型一个"粗略答案"，它能在此基础上精修，显著提升遮挡与弱纹理区域的深度质量。

3️⃣ 相机位姿camera_poses

位姿用四元数 + 平移向量表示，即(quats_xyzw, trans)元组（旋转 4 维、平移 3 维，对应 config.json 中cam_rot_quats_encoder的in_chans: 4与cam_trans_encoder的in_chans: 3）。

💡关键参数is_metric_scale：如果你的位姿来自 COLMAP 等 SfM 流程（只能确定到比例尺、没有真实米制单位），传入时加上"is_metric_scale": False，模型会通过内置的scale_encoder自动恢复度量尺度。

深度输入则是 1 通道的稠密编码器（depth_encoder，patch_size: 14），与上述编码器一起构成模型的"几何输入"通道。

🧩 任意组合：每个视图自由搭配

这正是 map-anything-apache-fp16 的精髓——不同视图之间互不干扰，同一视图内三种输入也可任意取子集。下面 3 个视图分别演示了"全量提供"、"仅内参"、"仅位姿（非度量尺度）"三种典型搭配：

views = processor.preprocess([ {"img": image0, "intrinsics": K0, "depth_z": depth0, "camera_poses": pose0}, {"img": image1, "intrinsics": K1}, {"img": image2, "camera_poses": (quats_xyzw, trans), "is_metric_scale": False}, ]) predictions = model.infer(views)

典型使用场景对照：

📤 预测输出字段说明

调用model.infer(views)后，每个视图返回一个字典（惰性求值，用mx.eval触发计算）：

⚡ 命令行一键推理

不想写代码时，可直接用命令行，所有输出会写入predictions.npz，并额外导出一份彩色点云points.ply：

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

🛠️ 进阶小贴士

1. 记得设置MLX_ENABLE_TF32=0：在 M5 及更新 GPU 上，MLX 默认以 TF32 精度执行 float32 矩阵乘，会让 float32 的预测头成为最大误差来源。在首次矩阵乘之前设置该变量可避免问题，只多花几毫秒。
2. 分辨率预处理：模型采用固定映射到 518 的分辨率集（preprocessor_config.json 中resize_mode: fixed_mapping、resolution_set: 518），输入图会被自动规整。
3. 精度实测：在 518×294 的 4 帧室外视频上，与 float32 PyTorch 参考实现相比，深度（尺度归一化后）中位相对误差约 6.0e-4，度量尺度误差在 1.1e-4 以内，与参考实现在 MPS 上的混合精度表现持平。
4. 速度参考（Apple M5 Max，518×294 视图，MLX 本模型 vs PyTorch MPS 混合精度）：

📚 仓库文件资料速查

✅ 一句话总结：把你能拿到的内参、深度图、相机位姿"有多少给多少"，map-anything-apache-fp16 就能在 Apple Silicon 上以毫秒级推理给你一套度量级的 3D 重建结果。