零样本立体匹配快速上手：FoundationStereo 从环境搭建到 3D 点云输出指南

零样本立体匹配快速上手：FoundationStereo 从环境搭建到 3D 点云输出指南

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

刚买回一套双目相机，兴冲冲想给新场景做深度测量，传统立体匹配算法却立刻给你"泼冷水"：这个场景它没见过，需要重新收集数据、重新微调才能勉强出结果，换个环境又得重来一遍。FoundationStereo，这款斩获 CVPR 2025 最佳论文提名的零样本立体匹配开源项目，正试图终结这种"一景一训"的窘境——让任何陌生环境都能开箱即用。

先搞懂三件事：视差、零样本与合成数据 🧩

人眼是怎么"测距"的？

两只眼睛看向同一个物体，它在左右眼画面里的位置会有细微差异，这个差异就叫"视差"（disparity）。物体越近，视差越大；越远，视差越小。人脑正是靠这种天生的"立体匹配"感知距离，立体相机也遵循同样的逻辑：模型算出左右图逐像素的视差，便得到一张视差图。

"零样本"到底意味着什么？

传统深度立体匹配算法在公开数据集上成绩斐然，但那属于"考过的题"；遇到没见过的新场景，精度就明显下滑，通常需要针对该领域做微调。而"零样本"（zero-shot）意味着：模型在没有接触过你场景的前提下，直接推理就能拿到可用结果。这正是 FoundationStereo 的核心价值——它让立体匹配第一次拥有了基础模型式的泛化能力。

为什么用合成数据训练？

要让模型"见多识广"，官方构建了包含 100 万对立体图像的合成训练集（FSD 数据集），覆盖丰富场景与高真实感渲染，并配套一条自动自校准管道，把模糊、有歧义的样本自动剔除，从源头保证"喂给模型的都是好题"。再通过 side-tuning 骨干网络借用 DINOv2 等视觉基础模型的单目先验来弥补合成域与真实域的差距，配合长程上下文推理做代价体过滤。这套组合拳的成果是：在 Middlebury 与 ETH3D 两个国际权威排行榜上双双登顶第一。

图注：上图依次为左视图、右视图和视差可视化。颜色越暖代表视差越大，即物体离相机越近。

一次看懂输出：视差图、深度图与点云

FoundationStereo 的直接输出是视差图。把相机内参和基线（左右相机之间的距离）代入公式"深度 = 焦距 × 基线 ÷ 视差"，即可换算成带真实尺度（米）的深度图，进而生成 3D 点云。看懂这条链路，你就明白为什么官方 demo 会同时产出视差可视化、depth_meter.npy和cloud.ply三类文件。

从零跑通：四步上手路线 🚀

第一步：准备硬件与环境

官方已在 Linux 下的 3090、4090、A100、V100 及 Jetson Orin 上验证过，推理对显存有一定要求，建议优先保证 NVIDIA GPU 可用。环境搭建推荐使用 conda：

git clone https://gitcode.com/gh_mirrors/fo/FoundationStereo cd FoundationStereo conda env create -f environment.yml conda run -n foundation_stereo pip install flash-attn conda activate foundation_stereo

为什么 flash-attn 要单独安装？因为它在环境创建阶段容易引发冲突报错，单独装一步能有效避开这个官方都重点标注过的坑。

第二步：获取预训练权重

下载基础模型后，把整个权重文件夹（例如23-51-11）放到项目根目录下的./pretrained_models/里。官方提供了两个通用权重：23-51-11（基于 ViT-Large，精度更佳）和11-33-40（基于 ViT-Small，速度更快）。新手建议直接用前者，质量更有保障。

第三步：跑通官方 demo

回到项目根目录，执行：

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/

它会读取仓库自带的左右图，输出视差可视化，并弹窗展示 Open3D 点云，按 ESC 退出。为什么能"开箱即用"？因为示例内参文件 assets/K.txt（第一行是 1×9 的内参矩阵，第二行是以米为单位的基线）已经替你填好，模型无需任何额外设置。

第四步：换成自己的数据并解读结果

替换左右图路径，再按同样格式准备内参文件即可。关键前提：左右图必须是已校正（极线对齐、无鱼眼畸变）的立体像对；大多数商用双目相机（如 ZED、RealSense）出厂已处理妥当，直接导出就能用。

图注：Open3D 渲染的彩色点云，每个点都带原始 RGB 颜色，场景三维结构一目了然。

遇到问题怎么办：高频坑位排雷 ⚠️

• 不输出或输出残缺点云：先确认内参文件格式正确；再调点云相关参数，如--z_far（裁剪最大深度）、--remove_invisible（剔除左右图不重叠的不可靠点）、--denoise_cloud（离群点去噪）。
• 报CUDNN_STATUS_NOT_SUPPORTED错误：多半是显存不足（OOM）的信号，把分辨率降下来（如--scale 0.5）或换更大显存的显卡即可。
• 图像超过 1000px 时卡顿：两种解法——加--hiera 1开启分层推理拿到全分辨率深度（较慢），或调小--scale换取速度。
• GPU 不支持 flash-attn：老显卡的常见困扰，官方 FAQ 与相关 issue 中已有替代方案，可直接检索关键词定位。
• 左右图传反：左图必须来自左侧相机（画面中物体应更靠右），传反会得到完全错误的视差。

它能用在哪儿？与下一步建议 🌟

零样本立体深度估计的想象空间很大：自动驾驶与机器人导航中，车辆和机械臂面对陌生环境也能实时感知三维结构；增强现实里，虚拟物体可以被更自然地锚定到真实场景；遥感测绘中，无人机航拍影像同样能借它提取地形信息。若对推理速度有极致追求，还可参考 README 中的 TensorRT 方案，官方在同一张 3090 上实测获得约 6 倍加速。

下一步建议从三件事入手：先完整跑通 demo 感受流程，再用自己的双目相机数据复现一次，最后阅读core/目录下的源码，理解视差是如何一步步变成点云的。遇到疑问优先查看 README 的 FAQ 与python scripts/run_demo.py --help，它们覆盖了绝大多数常见问题。

从"换一个场景就要重新微调"，到"任何陌生环境开箱即用"，FoundationStereo 迈出的这一步，让我们离"机器像人眼一样看世界"的愿景更近了一点。希望这份指南能帮你顺利迈出第一步，剩下的，就交给你的想象力了。

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