简介这是一份面向计算机视觉初学者的三维重建算法源码包聚焦单目与双目视觉的深度估计与三维点云生成适合作为课程设计、毕业设计或期末大作业的参考实现。压缩包共41个文件大小约80.22MB包含3个Python脚本单目重建、双目重建、图像拼接、2个算法说明文本、1个README说明文档以及35张用于测试的实拍场景图片代码与数据配套下载后即可直接运行实验。目前已有188人学习对于需要快速搭建三维重建实验环境的读者有一定参考价值。通过阅读源码与运行demo可以了解特征提取、视差计算、深度恢复等关键环节的具体实现并结合多组不同场景的样例图片观察重建效果。资源结构清晰适合在现有基础上二次开发也可作为论文复现与算法对比的起点。1. 单目双目三维重建不是二选一先想清楚你的输入是几张图拿到一个名为“单目双目视觉三维重建算法python源码.zip”的压缩包很多人第一反应是拆开看里面是单目还是双目。但真正的问题不是“这个源码用了什么算法”而是“我手里的相机和数据适合走哪条路”。单目重建靠相机移动或多视角先验恢复三维结构双目重建靠左右视差直接反推深度两条路在后端的三角化、点云生成、坐标变换上高度重合差异主要在输入端和尺度处理上。我见过太多人在单目流程里纠结“为什么深度不准”或者在双目流程里抱怨“点云全是噪声”其实多半是没搞清楚输入约束。这个方向适合谁手里只有普通照片、监控视频、手机拍的一段移动镜头的人或者已经买了双目相机的机器人、测量、逆向建模从业者。Python的好处是验证快改一个参数就能看到视差图和点云的变化不用等编译。接下来我不按源码包的目录结构讲而是按“单目怎么做”“双目怎么做”“坑在哪”这条主线拆开讲你拿到任何同类项目都能快速定位到对应模块。2. 单目重建的两种落地路径特征点SFM和深度估计网络单目三维重建的“单目”指的是输入侧只有一台相机。想从单目还原三维本质上是不适定问题因为同一张图可能对应无数种三维场景。行业里常见的解法只有两条一是让相机动起来把多个视角的图像串起来做运动恢复结构也就是SFM二是让神经网络从单张图里直接回归深度图代表模型是MiDaS、DPT这类预训练网络。这两条路在Python源码里都能看到但输出含义完全不同前者得到稀疏点云后者得到逐像素的相对深度。很多人拿到单目源码后第一件事就是对着一张静态图调参数这其实是用错了方向。SFM至少需要两张有视差的图而且两张图之间必须有足够的平移否则对极几何约束会退化三角化出来的点不是发散就是飘到无穷远。下面先讲最基础的双视图SFM再讲深度估计网络的调用方式这两块吃透了单目源码里的分支逻辑基本就能看懂。2.1 双视图SFM本质矩阵与三角化的几何约束双视图SFM的核心思路是先在两张图里找到对应的特征点再从它们的像素坐标关系里恢复出相机之间的旋转和平移最后用相机位姿把对应点反投影回三维空间。这里的数学纽带是本质矩阵它只取决于相机内参和两帧之间的相对运动形式是 E [t]×R。虽然本质矩阵最少用5对点就能算但实践中为了抗噪声一般用RANSAC配合8点法或5点法做鲁棒估计。用OpenCV做这个流程时有几个前置条件必须满足第一相机内参K已知哪怕是用近似值也行但不能是单位阵第二两张图不能是纯旋转拍摄必须有平移分量第三特征点匹配的准确率要高否则后面RANSAC的内点比例太低。满足这三个条件后整个流程可以压缩到几十行代码里。import cv2 import numpy as np # 相机内参fx, fy, cx, cy来自标定或相机参数表 K np.array([[800.0, 0.0, 640.0], [0.0, 800.0, 360.0], [0.0, 0.0, 1.0]], dtypenp.float64) def sfm_pair(img1, img2, K): # 提取ORB特征nfeatures越大匹配越多但误匹配也越多 orb cv2.ORB_create(nfeatures3000, scaleFactor1.2, score_typecv2.ORB_HARRIS_SCORE) kp1, des1 orb.detectAndCompute(img1, None) kp2, des2 orb.detectAndCompute(img2, None) # 汉明距离暴力匹配crossCheck能过滤掉非对称匹配 bf cv2.BFMatcher(cv2.NORM_HAMMING, crossCheckTrue) matches bf.match(des1, des2) # 按距离排序取最近的前500个距离越小匹配越可靠 matches sorted(matches, keylambda m: m.distance)[:500] pts1 np.float32([kp1[m.queryIdx].pt for m in matches]) pts2 np.float32([kp2[m.trainIdx].pt for m in matches]) # RANSAC估计本质矩阵threshold是内点到极线的最大像素距离 E, inlier_mask cv2.findEssentialMat( pts1, pts2, K, methodcv2.RANSAC, prob0.999, threshold1.0) # 从本质矩阵分解出旋转和平移注意E可能对应4组解 _, R, t, inlier_mask cv2.recoverPose(E, pts1, pts2, K, maskinlier_mask) # 构造投影矩阵并三角化 P1 K np.hstack((np.eye(3), np.zeros((3, 1)))) P2 K np.hstack((R, t.reshape(3, 1))) pts4d cv2.triangulatePoints(P1, P2, pts1.T, pts2.T) pts3d pts4d[:3] / pts4d[3] # 齐次坐标转三维 inlier_idx inlier_mask.ravel().astype(bool) return pts1[inlier_idx], pts2[inlier_idx], R, t, pts3d.T[inlier_idx]这段代码里的参数值得展开说。nfeatures3000面对纹理丰富的场景通常够用但如果图像是室内白墙ORB提取的特征点会集中在少数纹理区域这时可以降低到1500左右避免匹配点扎堆。score_typecv2.ORB_HARRIS_SCORE会让特征点更分散默认的FAST_SCORE更快但容易聚团。threshold1.0表示内点到极线的距离小于1像素这个值越大内点越多但位姿估计越粗对1080p图像0.8到1.5都是常见范围。三角化输出的pts3d是在第一帧相机坐标系下的三维点单位取决于平移向量的尺度。recoverPose返回的t是归一化向量模长为1所以整个点云的尺度是任意的。这是单目SFM最需要接受的现实你能得到形状得不到物理尺寸。如果要恢复米制尺度必须知道场景里某段距离的真实长度或者相机在两个时刻的实际位移。2.2 从两张图扩展到多帧增量式SFM的工程写法双视图只是SFM的骨架。真实重建时相邻帧之间的位姿误差会累积时间长了轨迹飘移点云也在末端散开。工程上一般用增量式方法先挑一对基线好、匹配多的图做初始重建然后把新帧通过特征匹配挂到已有的三维点上用PnP求解相机位姿再把新观测到的点做三角化最后用Bundle Adjustment统一优化所有位姿和三维点。Python里自己实现完整Bundle Adjustment很吃力常见的做法是调用OpenCV的cv2.solvePnPRansac做位姿估计再用g2o或ceres的Python绑定做优化。如果你拿到的源码包里有“incremental_pipeline.py”之类的文件里面大概率就是这套逻辑。新手可以直接先跑通双视图再考虑扩展多帧否则一上来就被BA的雅可比矩阵劝退。2.3 深度学习单目深度估计MiDaS和DPT的接入姿势深度学习单目深度估计和SFM完全不同它不求解几何而是从大量真实深度数据里学出先验。以MiDaS为例输入是一张RGB图输出是逆深度图值越大的像素离相机越近。这类模型在室内外场景都有不错的相对深度效果但做不了度量重建除非额外加一个尺度校准步骤。import torch import cv2 import numpy as np # 加载MiDaS小模型适合CPU快速验证 model torch.hub.load(intel-isl/MiDaS, MiDaS_small) model.eval() transform torch.hub.load(intel-isl/MiDaS, transforms) trans transform.small_transform img cv2.cvtColor(cv2.imread(input.jpg), cv2.COLOR_BGR2RGB) input_batch trans(img)[image].unsqueeze(0) with torch.no_grad(): depth model(input_batch) # 缩放到原图尺寸 depth torch.nn.functional.interpolate( depth.unsqueeze(1), sizeimg.shape[:2], modebicubic, align_cornersFalse, ).squeeze(1).squeeze(0).numpy() # 逆深度转可视化先归一化到[0,1] depth_norm (depth - depth.min()) / (depth.max() - depth.min()) cv2.imwrite(depth_midas.png, (depth_norm * 255).astype(np.uint8))这段代码里有两个关键点。第一MiDaS_small的输出是逆深度而且尺度在每张图上都不同换一张图可能整体数值范围变化很大所以必须做归一化才能可视化或送去后处理。第二torch.hub.load需要联网下载权重如果你的环境离线需要手动把权重文件放到~/.cache/torch/hub下否则会在加载时卡住。把MiDaS的深度图转成点云时还需要相机内参三维坐标 x (u - cx) * depth / fxy (v - cy) * depth / fyz depth。这里的depth是相对值所以点云形状通常能看但尺度不对。如果你看到源码里把深度学习输出直接当真实深度用基本可以判断作者没有做过尺度标定。3. 双目重建的完整链路标定、极线校正、SGBM和点云生成双目重建在原理上比单目多了一个约束左右相机基线B已知深度 Z f·B/d其中d是左右图对应点的视差。只要能得到准确的视差图深度计算就是一步的事。但视差图的质量被三个环节死死卡住相机标定准不准、极线校正对不对、立体匹配参数贴不贴场景。这三个环节在Python源码里都有对应的OpenCV模块下面按顺序走一遍。3.1 双目标定与极线校正先让左右图变成“整齐”的两行立体匹配的前提是左右图的对应点必须在同一水平线上这要靠极线校正实现。校正前必须先标定出左右相机的内参、畸变系数和相对外参。标定棋盘格时建议至少采集20对图像并且覆盖画面的四个角和中心区域同时要有明显的倾斜角度。如果只拍正对相机的一组图畸变参数会被误判后续校正出来边缘全是拉伸。import cv2 import numpy as np # 假设已经用calibrateCamera得到左右相机内参和畸变 # K1, D1, K2, D2, R, T 来自单目标定和双目标定 # image_size 是校正前图像尺寸 R1, R2, P1, P2, Q, roi1, roi2 cv2.stereoRectify( K1, D1, K2, D2, image_size, R, T, alpha0.0, flagscv2.CALIB_ZERO_DISPARITY ) # 计算左右视图的映射表用remap一次性处理整张图 map1x, map1y cv2.initUndistortRectifyMap( K1, D1, R1, P1, image_size, cv2.CV_32FC1) map2x, map2y cv2.initUndistortRectifyMap( K2, D2, R2, P2, image_size, cv2.CV_32FC1) left_rect cv2.remap(left_img, map1x, map1y, cv2.INTER_LINEAR) right_rect cv2.remap(right_img, map2x, map2y, cv2.INTER_LINEAR)stereoRectify里的alpha参数影响校正后图像的缩放。alpha0.0表示只保留有效像素区域图像会被裁剪得更小但边缘畸变最小alpha1.0保留所有像素但边缘会出现黑边。工程上常用alpha0.0因为它能减少无效视差区域。flagscv2.CALIB_ZERO_DISPARITY要求两个视图的视差零平面对齐适合大多数标准配置。校正完成后可以用cv2.line在两张图上画水平线观察同一物体是否落在相同行。如果看到明显的上下偏移说明T向量里的y分量估计有问题回查标定板的角点检测。3.2 SGBM立体匹配五个参数决定点云是“干净”还是“糊成一片”立体匹配算法里OpenCV的StereoSGBM是工程上用得最广的。它属于半全局匹配把每个像素的匹配代价沿着多个方向做动态规划在精度和速度之间取平衡。直接调用很简单但参数不调的话默认值基本只能出废墟级视差图。def create_sgbm(min_disp0, num_disp128, block_size9): # num_disp必须是16的倍数决定最大视差范围 stereo cv2.StereoSGBM_create( minDisparitymin_disp, numDisparitiesnum_disp, blockSizeblock_size, P18 * 3 * block_size ** 2, P232 * 3 * block_size ** 2, disp12MaxDiff1, uniquenessRatio5, speckleWindowSize150, speckleRange2, modecv2.STEREO_SGBM_MODE_SGBM_3WAY ) return stereo stereo create_sgbm() disparity16 stereo.compute(left_rect, right_rect).astype(np.float32) # SGBM输出的视差是整数乘以16所以除以16得到真实像素视差 disparity disparity16 / 16.0 valid_mask (disparity 0.0) (disparity (num_disp / 16.0))这里每一个参数都踩过坑。blockSize是匹配窗口边长必须为奇数推荐5到11窗口越大视差图越平滑但边缘被侵蚀得越厉害3个像素的细小物体直接消失。P1和P2是平滑惩罚项P2一般设为P1的4到8倍P2太大会把真实的深度突变磨平太小则噪声满天飞。uniquenessRatio表示次优匹配代价必须比最优代价高多少百分比才接受该视差5到15之间常用调太高会让很多像素没有有效视差。speckleWindowSize和speckleRange用来滤除视差图上的小孤岛。speckleWindowSize150表示小于150个连通像素的斑点会被归零speckleRange2表示斑点内视差变化不超过2才会被当成一个区域。对近距离大物体可以放宽WindowSize到500远距离小物体则要减小。提示如果场景深度范围大比如同时有0.5米和5米的物体numDisparities需要设到160以上。但numDisparities越大计算越慢更聪明的做法是先做一次粗略视差估计确定深度范围后再缩小搜索区间。3.3 视差转深度与点云生成直接调用Q矩阵或手写投影公式得到视差图后转点云有两条路一条是用stereoRectify输出的Q矩阵直接调cv2.reprojectImageTo3D另一条是根据公式逐像素计算。Q矩阵法更推荐因为OpenCV已经替你把主点偏移、基线长度、像素焦距全部打包好了不容易出错。def disparity_to_pointcloud(disparity, Q, image_bgr): # Q矩阵来自stereoRectify负责把视差映射到三维坐标 points cv2.reprojectImageTo3D(disparity, Q, handleMissingValuesTrue) # 过滤无效视差和过远点 mask (disparity 0.0) (disparity disparity.max()) \ np.isfinite(points[..., 2]) cloud points[mask].reshape(-1, 3) colors image_bgr[mask].reshape(-1, 3)[:, ::-1] # BGR转RGB return cloud, colors cloud, colors disparity_to_pointcloud(disparity, Q, left_rect) # 保存为PLY格式供开源工具可视化 # 这里省略ply写入逻辑open3d的write_point_cloud是常用方案reprojectImageTo3D的输入视差必须是float32且是真实像素值不是倍数后的整数。handleMissingValuesTrue会把无效点变成一个大负数所以必须配合mask过滤。如果你发现点云里有大量坐标超过1e8的点基本就是mask条件没写全把负值点也塞进来了。如果不用Q矩阵手写公式也简单Z f * B / dX (u - cx) * Z / fxY (v - cy) * Z / fy。这里的基线B和焦距f必须单位一致通常都是毫米。手写的好处是能控制深度裁剪范围比如想只保留1到10米内的点在公式里加一个np.where就行。4. 避坑指南三维重建里最容易让结果翻车的六个细节写到这里原理和代码路径都清楚了。但真实跑起来你遇到的第一波问题往往不是算法复杂度而是“看起来哪里不对”。这一章把我自己踩过的坑按“现象→原因→解决”列出来每条都能对上具体的调试点。4.1 现象点云像被揉碎了一样全是飞点飞点就是那些孤零零飘在主体之外的散点数量多时点云完全没法看。原因通常是视差图上的噪声点没有经过滤波或者disparity的mask写成了disparity 0把弱纹理区域的错误视差也放进来了。解决分三步第一在SGBM参数里增大P2让平滑项更强势压制小尺度噪声第二把uniquenessRatio提到10以上逼着算法只接受高置信度的匹配第三在生成点云前先对视差图做中值滤波或用cv2.filterSpeckles滤除小斑点。飞点严重的场景还可以对深度图做连通域分析只保留最大连通域。4.2 现象单目重建出来的尺度完全不对单目SFM和深度学习深度估计都存在尺度问题。SFM的平移向量是归一化的点云整体可能被放大或缩小到和真实物体差一个数量级深度学习的深度图更是和真实尺寸毫无关系。解决方法是引入一个参照物。最简单的是在场景里放一块已知尺寸的标定板或刻度尺重建后测量点云上对应两点距离计算缩放因子然后整体对齐。更严谨的做法是在SFM里融入GPS或IMU的绝对位移信息用真实平移长度约束三角化结果。如果只是做视觉演示归一化点云到包围盒内即可。4.3 现象极线校正后左右图依然有垂直偏差校正完在图上画水平线发现同一特征点不在同一行说明stereoRectify的输入参数不可靠。最常见的原因是标定用的棋盘格图像不是双目相机同一时刻拍摄的或者拍摄张数太少导致T向量的y分量估计错误。解决方法是重新采图确保左右相机同步触发至少20对且棋盘格要出现在画面的不同位置和角度。采完图后先用cv2.stereoCalibrate做双目标定检查重投影误差误差大于0.5像素就要剔除异常图像对。另外initUndistortRectifyMap里的image_size要与实际图像尺寸完全一致如果写错校正后的图会整体偏移。4.4 现象SGBM跑起来特别慢一帧要算好几秒慢的原因通常是numDisparities太大、blockSize太大或者图分辨率太高。比如对1080p的图numDisparities256加上blockSize15计算量会非常爆炸。解决思路是按需缩放。先把图像缩小到一半计算视差图再插值回原尺寸预览参数用缩略图最终渲染再用全分辨率。另一个常用技巧是分区域匹配先算低分辨率视差只把深度范围锁定在目标区间再按这个区间设置minDisparity和numDisparities。如果纯CPU计算仍然慢可以考虑用cv2.StereoSGBM_create的modecv2.STEREO_SGBM_MODE_HH或HH4但注意这只是调整速度优先级不一定比SGBM_3WAY快。4.5 现象标定很准确但重建的平面是弯曲的平面变曲面最常见的元凶是畸变校正没生效。有些源码只做了undistort但把校正后的图重新映射时用了原图的映射表或者remap的map类型是CV_16SC2导致亚像素精度丢失。解决方法是回查initUndistortRectifyMap输出的map类型推荐用CV_32FC1。另外确认畸变系数D是紧凑的5参数还是8参数模型k1,k2,p1,p2,k3如果标定时用了CALIB_RATIONAL_MODEL后面的undistort也要对应。还有一个隐形坑是remap之前把图像类型转成了灰度图但Q矩阵里的主点坐标是基于彩色图尺寸的尺寸不一致也会导致坐标偏移。4.6 现象三角化出来的点在空间里扭曲成弧形用双视图SFM时如果两张图之间的平移太小三角化会在深度方向产生巨大不确定性点云呈现一条弧线。这是因为基线太短视差噪声被放大成了深度误差。解决方法是保证相邻帧之间有足够平移通常要求两帧之间的视差平均大于10像素。如果做视频序列可以每间隔5到10帧选一对关键帧而不是逐帧重建。也可以用cv2.triangulatePoints之后检查点的重投影误差误差大于1像素的点直接剔除。5. 验证重建效果的实用技巧先测误差再看点云很多人把点云可视化当成验证的终点但点云看着“像”并不代表重建准。我现在的习惯是先用定量指标测一遍误差再用Open3D看可视化最后调参数。定量验证分两种有真值的场景和没有真值的场景。有真值时就简单了。如果你用的是仿真数据集或已知深度图的数据集直接把重建出的深度和真值做比较计算RMSE或相对误差。双目重建场景里用标定板的角点在左右图上的投影位置验证立体匹配精度也是靠谱的办法。没有真值时可以放一个已知尺寸的盒子或棋盘格重建后测量点云上对应两个点的三维距离和真实长度对比算出误差百分比。这个百分比就是你调整SGBM参数和滤波强度的依据。点云可视化方面Open3D比Matplotlib高效得多一个o3d.visualization.draw_geometries就能交互旋转缩放。我常写一个很小的工具函数把disparity_to_pointcloud的输出直接喂给Open3D并加上按深度染色的色带。这样能看到三个问题点云密度是否均匀、边缘是否锐利、深度梯度是否自然。边缘糊成一片说明blockSize太大密度不均匀说明弱纹理区域被过度滤除。还有一个容易被忽略的验证技巧把重建的三维点重新投影回原图叠加原始图像查看重投影误差。这一步能同时暴露相机内参误差、匹配错误和位姿漂移。如果你做的项目要落地到测量或机器人导航这个重投影误差必须作为上线指标持续监控而不是只看一眼点云效果。希望这些细节能帮你少走弯路。本文还有配套的精品资源点击获取