FoundationStereo 零样本立体深度估计完整指南：从视差原理到你的第一份三维点云

【免费下载链接】FoundationStereo[CVPR 2025 Best Paper Nomination] FoundationStereo: Zero-Shot Stereo Matching项目地址: https://gitcode.com/gh_mirrors/fo/FoundationStereo

机器人、无人机、自动驾驶汽车靠什么感知世界的远近？答案常常是立体深度估计——用一对双目图像推算每个像素的深度。FoundationStereo 就是这样一款面向零样本立体深度估计的开源项目，它荣获 CVPR 2025 最佳论文提名，无需针对任何场景重新训练，就能直接输出高精度的视差图与三维点云。这篇指南会带你从原理走到实操，完整跑通一次零样本立体深度估计流程，亲手得到一份可以拖拽查看的三维点云。

上图是 FoundationStereo 的典型输出：输入一对校正后的立体图像，即可得到逐像素的视差图，颜色由冷到暖，表示物体由远及近。

一双眼睛的魔法：立体匹配是怎样工作的 🧩

先讲一个你每天都在做、却很少留意的事情：为什么我们闭上一只眼睛时，判断距离会变得困难？

因为两只眼睛之间存在一个固定间距，这个间距在专业术语里叫基线（baseline）。你伸出一根手指放在眼前，交替闭上左眼和右眼，会发现手指相对背景发生了明显位移；而远处的山峰，无论怎么换眼，几乎纹丝不动。这个"位移量"就是视差（disparity）：物体越近，视差越大；物体越远，视差越小。

立体匹配算法要做的，就是替计算机自动找出左右两张图像中"同一个物理点"的对应关系，算出每个像素的视差，最终拼出一张完整的视差图。你可以把它想象成一部电影在两个机位同时拍摄，算法就是那位逐帧核对画面、量出"镜头偏移量"的剪辑师。

FoundationStereo 的内部管线也遵循这条主线，只是每一步都做了强化：

• 特征提取：采用侧调优（side-tuning）的特征骨干网络，把 DINOv2、Depth Anything V2 这类单目视觉基础模型习得的丰富先验"嫁接"进来，弥补合成数据与真实世界的差距；
• 代价体构建与滤波：计算左右特征之间的匹配代价，再用长距离上下文推理机制对代价体做全局滤波，减少歧义匹配；
• 迭代细化：像 RAFT 一样通过多轮更新逐步打磨视差结果。

这些设计共同决定了它的核心竞争力——零样本泛化能力。

零样本从何而来：百万级数据与自校准管道 🧪

你可能想问：为什么传统的立体匹配模型一换场景就"水土不服"，而 FoundationStereo 可以直接拿去做推理？

关键在于训练数据。研究团队构建了一个包含100 万对立体图像的大规模合成数据集（FSD），刻意追求场景多样性与照片级写实度——从厨房桌面到室内房间，各种光照、材质和布局都被覆盖。更难能可贵的是，他们设计了一套自动自校准管道：自动剔除那些左右视图信息模糊、无法可靠标注的样本，确保进入训练的每一对图像都"干净可学"。

于是，模型见到的是足够丰富、足够真实的"世界样本库"，而非某一个特定数据集的偏好。这正是"零样本"的底气：它在训练时见过足够多的世界，所以在推理时敢于面对没见过的场景。

实操准备：一台 GPU 和一对合格的立体图像 💻

在动手之前，先确认三件事。

第一，硬件。项目在 NVIDIA GPU 上运行，官方测试过的型号包括 RTX 3090、4090、A100、V100 以及 Jetson Orin。其他型号通常也能跑，但要留意显存是否够用。如果没有 GPU，也可以把它当成学习项目先在 CPU 上体会流程，正式推理还是建议用 GPU。

第二，数据。输入的左右图像必须满足三个条件：

• 左右图像分辨率一致；
• 已经过校正与去畸变（即极线水平对齐，没有鱼眼镜头的桶形畸变）；
• 不要搞错左右顺序，左图必须来自左相机（左图中的物体看起来会"更靠右"）。

如果你用的是 ZED、RealSense 这类双目标定相机，它们通常已经替你完成了校正，直接使用即可。项目自带的样例数据就很典型：

以上是项目自带的一对左右视图，一张桌面场景图：键盘、马克杯、纸巾盒、显示器都清晰可见，两图之间存在细微的视角差异。

第三，格式。推荐使用无损失的 PNG 格式，避免 JPEG 压缩带来的伪影。值得一提的是，官方也实测过单目灰度图与红外立体图像（如 RealSense D4XX 系列），效果同样不错。

完整实操：从安装到第一份点云 🚀

下面进入正题，跟着步骤走一遍完整的推理流程。

第一步：克隆仓库并创建环境

打开终端，克隆项目并进入目录：

git clone https://gitcode.com/gh_mirrors/fo/FoundationStereo cd FoundationStereo

然后基于官方提供的配置文件创建 Conda 环境：

conda env create -f environment.yml conda run -n foundation_stereo pip install flash-attn conda activate foundation_stereo

这里有个小细节：flash-attn（Flash Attention）需要单独安装，因为它有时会导致环境创建中途报错。如果你的 GPU 不支持 Flash Attention，也可以参考社区给出的替代方案，绕开它继续使用。

第二步：下载预训练模型

项目提供两个零样本推理模型，按需选择：

下载后，把整个文件夹（例如23-51-11）放到项目根目录下的./pretrained_models/里，保持目录结构即可。

第三步：运行你的第一次推理

确认一切就绪后，执行下面这条命令：

python scripts/run_demo.py --left_file ./assets/left.png --right_file ./assets/right.png --ckpt_dir ./pretrained_models/23-51-11/model_best_bp2.pth --out_dir ./test_outputs/

程序会依次完成读取图像、填充到模型所需的尺寸、推理、反填充，并把结果保存到./test_outputs/目录。在推理完成后，屏幕上会自动弹出一个 Open3D 窗口，你看到的将是这个场景的完整三维重建：

这是运行 demo 后生成的点云在 Open3D 中的展示：桌面、键盘、纸巾盒、马克杯都以三维形式被重建出来，你可以旋转视角从任意角度观察。

第四步：认识输出文件

推理结束后，./test_outputs/目录里会出现几类结果，用途各不相同：

• vis.png：把原始左图与视差可视化并排拼接的预览图；
• depth_meter.npy：以米为单位的稠密深度图（NumPy 格式），方便后续用 Python 处理；
• cloud.ply：三维点云文件，可以用 Open3D、CloudCompare 等工具打开；
• cloud_denoise.ply：经过离群点去除后的点云，通常更干净。

第五步：为你的数据生成点云

如果想把点云用在自己的图像上，需要额外提供一个内参文件，告诉模型"我的相机是什么参数"。文件格式非常简单：第一行是摊平后的 3×3 相机内参矩阵（共 9 个数字），第二行是左右相机之间的基线距离，单位是米。项目自带的assets/K.txt就是标准示例，其中基线约为 0.063 米。

视差图、深度图与点云：三个概念一次说清 ❓

第一次接触立体视觉的人，常常被这三个词绕晕。其实它们的递进关系很清晰：

连接视差与深度的是一道简洁的公式：

depth = 焦距(像素) × 基线(米) / 视差(像素)

这再次呼应了开头的比喻：视差越大，深度越小，物体越近。模型输出的视差图经过这道换算，再结合相机内参反投影，就变成了三维点云。理解了这层关系，你就明白了为什么run_demo.py的参数里既要点云裁剪距离（--z_far），也要读内参文件——每一步都在为"从像素到米"铺路。

让推理更快：分辨率、迭代次数与 TensorRT ⚡

实际部署时，速度和精度往往需要权衡。项目提供了几个非常实用的调节旋钮：

• 降低输入分辨率：在命令中加入--scale 0.5，把图像缩小一半再推理，速度明显提升，适合对精度要求不那么苛刻的场景；
• 减少细化迭代次数：默认迭代 32 轮，可加--valid_iters 16，用少量精度换取显著提速；
• 高分辨率图像用分层推理：当输入图像超过 1000 像素时，加--hiera 1启用分层推理，可以在全分辨率下输出结果，代价是速度变慢；
• 追求极致速度：TensorRT。项目支持把模型导出为 ONNX 再转成 TensorRT FP16 引擎（官方实测在 RTX 3090 上约有 6 倍加速）。需要说明的是，ONNX/TRT 版本目前只支持 Docker 部署方式，仓库的docker/目录下已备好 Dockerfile 和启动脚本，按官方文档依次执行即可。

常见问题排查：遇到报错别慌 🛠️

首次运行大概率会遇到一两个坎，这里提前替你踩好坑。

报错RuntimeError: cuDNN error: CUDNN_STATUS_NOT_SUPPORTED？这通常意味着显存不足（OOM）。优先尝试缩小输入分辨率，或者换一块显存更大的 GPU。

没有生成点云，或点云残缺不全？检查与点云处理相关的参数：--z_far（最大深度裁剪）、--remove_invisible（剔除左右视图不可见区域）、--denoise_cloud（去噪）都会影响点云质量，按需调整即可。

没有双目相机，只有两台普通 RGB 相机？你可以先用 OpenCV 的stereoRectify等标定函数把两幅图像校正成标准的立体图像对，再送入 FoundationStereo。

想更深入了解每个参数？随时运行python scripts/run_demo.py --help，所有选项和说明都会列出来。

从桌面到旷野：FoundationStereo 能去哪里 🌍

从一个摆满杂物的桌面，到真实的户外街区，FoundationStereo 的零样本特性让它几乎可以"即插即用"：

• 自动驾驶：实时感知前方车辆与行人距离，为决策系统提供三维环境信息；
• 机器人导航：让机械臂或移动底盘理解场景结构，实现精准避障与抓取；
• 增强现实：把虚拟物体以正确的遮挡关系和透视效果"放"进真实空间；
• 遥感测绘：从航空或卫星立体影像中提取地形高程信息；
• 消费级设备：搭配 RealSense 等现成双目传感器，快速搭建三维感知应用。

值得一提的是，官方还提供了面向 Jetson 平台的部署指南（readme_jetson.md），边缘设备上同样可以运行。

回到文章开头的问题：设备如何"看见"距离？现在你已经有了完整的答案——一双经过校正的眼睛，加上一个零样本立体深度估计模型，就足够把二维图像还原成三维世界。这个曾属于专业实验室的领域，如今只需要几行命令就能亲手体验。不妨现在就克隆仓库、跑通 demo，让桌面上的杂物在你的屏幕上第一次拥有真实的深度。你的第一个立体深度估计项目，就从这里开始。

【免费下载链接】FoundationStereo[CVPR 2025 Best Paper Nomination] FoundationStereo: Zero-Shot Stereo Matching项目地址: https://gitcode.com/gh_mirrors/fo/FoundationStereo