简介：基于 Python 的三维重建算法 Structure from Motion（Sfm）实现代码，是一份面向高校计算机相关专业学生的课程设计与期末大作业源码包。内容聚焦 Sfm 三维重建核心流程，难度适中，源码均经过本地编译验证，评审分达到 98 分，并由助教老师审定，能够很好地满足学习、期末大作业和课程设计的实际需求。包内共 3 个文件，以两个 Python 脚本为主，分别承担主程序与参数配置，另含一个 Markdown 说明文档用于梳理实现思路，整体仅 5KB，结构精简，便于快速定位算法入口。目前已有 173 人学习下载，适合需要完成类似三维重建项目或入门该方向的 Python 开发者。借助这份资料，读者可以直接获得可运行的核心算法代码、清晰的配置模块以及分步说明文档，从而理解特征提取、特征匹配、运动恢复结构等关键环节，并在此基础上扩展自己的方案，节省从零搭建环境与调试的时间。
1. 基于 Python 的 SfM 三维重建：不靠深度学习，纯几何也能出点云
三维重建这几年几乎被 NeRF 和 3DGS 抢了风头，但如果你要做期末大作业、课程设计，或者想搞懂相机位姿估计和稀疏点云生成的底层逻辑，Structure from Motion（SfM）依然是绕不开的基石。这份基于 Python 的 SfM 实现代码，不依赖深度网络，不靠 GPU 堆算力，用一组普通照片就能重建出三维稀疏点云和相机位姿，评审分能到 98 分说明代码的完整度和稳定性都够扎实。它适合三类人：正在准备 Python 期末大作业的学生、想把特征提取到光束法平差这条链路跑通的新手，以及需要一份可修改的基线代码来做二次开发的从业者。核心价值在于，它能让你在一台普通笔记本上，用不到两百行核心逻辑完成一次完整的增量式重建。
2. SfM 代码结构与核心链路：从特征提取到稀疏点云
拿到这份资源之后，第一步不是急着跑，而是先把代码结构和 SfM 的完整链路对齐。很多人在课程设计里翻车，就是因为不知道每一步在做什么，改了参数也不知道影响哪个环节。
2.1 三个核心文件：revise_v2.py、config.py、README.md
压缩包解开之后，真正需要关注的代码文件就三个，结构非常干净，没有多余的东西。
| 文件 | 作用 | 关键内容 |
|---|---|---|
| revise_v2.py | 主流程实现 | SIFT 特征提取、匹配、基础矩阵估计、三角化、PnP、光束法平差 |
| config.py | 参数配置 | 特征提取参数、匹配阈值、RANSAC 阈值、可视化开关 |
| README.md | 使用说明 | 环境依赖、运行步骤、已知问题 |
这份代码的设计思路比较像课程作业的标准范式：主流程全部塞进一个脚本，配置单独抽出来，方便你在不碰核心逻辑的情况下调参。revise_v2.py 里的函数分层很清楚，extract_features、match_features、reconstruct这样的函数名一眼就能看懂，对照着 SfM 的经典流程去读，十分钟就能理清结构。
值得一提是它用的是 OpenCV 的 SIFT 实现，而不是自己造轮子。OpenCV 的 SIFT 由于专利问题在旧版本里需要contrib模块，新版（4.4 以上）直接集成在主库中，这一点在配置环境时能省不少事。
2.2 SfM 完整链路：特征提取到稀疏点云的五个关键环节
增量式 SfM 的核心链路可以拆成五个环节：特征提取与匹配、基础矩阵估计、三角化、PnP 求解相机位姿、光束法平差。这五个环节环环相扣，前面任何一步出了偏差，后面就跟着崩。
特征提取阶段用的是 SIFT，它对尺度变化和光照变化有很强的鲁棒性，比 ORB 和 SURF 更适合做重建。匹配阶段用的是 FLANN 匹配器加 Lowe 比率测试，比率值通常取 0.7 到 0.8 之间，越小误匹配越少，但匹配数也会变少。基础矩阵估计用的是 RANSAC 加八点法，这一步把外点过滤掉，为后面的三角化提供干净输入。
这里有个点容易被忽略：三角化出来的三维点是在相机坐标系下的，而 PnP 解决的是新增图像在已有三维点基础上的位姿估计。也就是说，SfM 不是一次性把所有的图都拿来算，而是先选两张重叠度高的图作为种子对，重建出一批三维点，然后一张一张往里面加。这份代码对输入的图片数量没有硬性限制，但从实践看，20 到 30 张图在普通笔记本上就能跑到分钟级，超过 50 张会明显变慢。
3. 环境配置与运行实操：用 config.py 控制整个重建流程
原理链路清楚了，接下来就是让它跑起来。这份代码在 Windows 和 Linux 上都能运行，我建议直接用 Anaconda 建一个虚拟环境，避免把系统 Python 搞乱。
3.1 依赖安装与最小环境配置
先创建一个干净的虚拟环境，然后安装依赖。以 Python 3.8 为例，常见的依赖包包括numpy、opencv-python、matplotlib、scipy。OpenCV 的版本建议不要低于 4.4，否则 SIFT 的调用方式会有差异。
# 创建 Python 3.8 虚拟环境 conda create -n sfm python=3.8 # 激活环境 conda activate sfm # 安装核心依赖 pip install numpy opencv-python matplotlib scipy注意opencv-python这个包名，不是opencv-contrib-python。新版 OpenCV 已经把 SIFT 挪到主库了，不需要额外装 contrib。装完之后验证一下 SIFT 能不能正常调用：
# 验证 SIFT 是否可用 import cv2 # 如果版本低于 4.4，这行代码会报错；4.4 以上直接可用 try: sift = cv2.SIFT_create() print("SIFT is ready, OpenCV version:", cv2.__version__) except AttributeError: print("SIFT not available, please upgrade OpenCV to >= 4.4")这一步能快速发现问题。我在 Windows 上遇到过装了旧版 OpenCV 导致 SIFT 无法调用的情况，现象是cv2.SIFT_create()直接报AttributeError，换成新版后立刻解决。
3.2 运行流程与参数调节要点
代码的运行入口在revise_v2.py的main函数里，它会读取config.py中的参数，然后对输入图片目录执行完整重建。默认的输入路径是项目下的images文件夹，你也可以在配置里改成自己的数据路径。
# config.py 中的核心参数 INPUT_IMAGE_DIR = "images/" # 输入图片目录 OUTPUT_DIR = "output/" # 输出目录，存放点云和相机位姿 SIFT_NFEATURES = 2000 # 每张图提取的最大特征点数 MATCH_RATIO = 0.75 # Lowe 比率测试阈值，越小越严格 RANSAC_THRESHOLD = 0.5 # RANSAC 内点距离阈值 INLIER_THRESHOLD = 0.01 # 基础矩阵内点判定阈值SIFT_NFEATURES是每张图片提取的特征点数量上限。对于 1000 万像素左右的图片，2000 个特征点足够产生稳定的匹配；如果图片纹理较少，可以提高到 3000，但会增加匹配耗时。MATCH_RATIO是最需要敏感度的参数，我一般把它固定在 0.7 到 0.8 之间，低于 0.6 会导致匹配数量骤减，高于 0.85 会引入大量误匹配，后面三角化和 PnP 的精度都会受影响。
RANSAC_THRESHOLD的单位是像素，它表示一个点被当作内点的最大重投影误差。0.5 像素是个比较保守的值，适合清晰度较高的图片；如果图片有轻微模糊或者压缩痕迹，可以放宽到 1.0，否则内点太少会导致位姿估计失败。
3.3 运行后如何判断重建是否成功
运行完成后，输出目录里会生成两个核心文件：sparse_points.ply和camera_poses.txt。前者是稀疏点云，可以用 CloudCompare 或者 MeshLab 打开；后者记录每一帧的相机位置和姿态。
判断重建是否成功，不要只看程序有没有报错。打开点云文件，如果看到一团均匀分布的三维点，说明三角化质量不错；如果点云中出现了大量飞到远处的孤立点和明显的条纹状分布，说明匹配或三角化环节有问题。相机位姿文件里，相邻帧的相机位置应当平滑过渡，如果出现相邻两帧的相机位置发生大跨度跳跃，那大概率是 PnP 解算时初值给得不好。
4. 避坑指南：SfM 实现中常见的五个翻车点
这部分每一行都是血泪经验。SfM 这门手艺的坑位非常固定，几乎每个踩过的人都是在同样几个地方栽的跟头。我列了五个高频问题，按“现象、原因、解决”的方式写出来，建议直接对照排查。
4.1 特征点数量足够但匹配数量接近为零
现象：SIFT_NFEATURES已经设置到 3000，但两张高度重叠的图片匹配出的点数只有十几个，程序在基础矩阵估计阶段直接报错。
原因：图片之间有严重的亮度差异或存在大面积的重复纹理。SIFT 描述子是基于灰度梯度的，如果两张图一张过曝一张欠曝，描述子的欧氏距离会非常大，阈值内的匹配自然减少。
解决：在特征提取前做一次直方图均衡化。OpenCV 的cv2.equalizeHist可以对灰度图做全局均衡，能明显提升匹配数量。另外检查一下MATCH_RATIO是否被改得过低，0.6 以下是高危区间。
4.2 点云出现大量从原点放射状的飞点
现象：重建出的点云中，相当一部分点分布在一条从原点向外扩散的直线上，看起来像一把撑开的伞骨。
原因：相机内参不准确，或者图片没有做畸变校正。SfM 默认使用针孔相机模型，如果照片是用广角镜头拍的，画面边缘的畸变会让三角化的外极线约束失效，导致深度估计严重错误。
解决：如果图片来源是手机或单反，需要先做畸变校正。OpenCV 提供了cv2.undistort，但前提是你知道相机的内参矩阵和畸变系数。如果不知道，最简单的方法是先用 SfM 自带的 bundle adjustment 去估计内参，不要把内参矩阵写死。
4.3 增量式重建到某一张图时程序卡死或内存暴涨
现象：程序前面几张图运行正常，到接近中间位置时突然卡顿超过几十秒，随后内存飙升，最终进程被系统杀掉。
原因：这一步通常发生在 PnP 求解时，已有的三维点数量太多，而新图片的特征点与这些三维点的对应关系计算量庞大。尤其是没有对已有三维点做管理的情况下，匹配矩阵会变得极其稠密。
解决：检查config.py里是否有类似MAX_POINTS_PER_VIEW或MAX_CORRESPONDENCES的限制参数。如果没有，在代码中每张图保留与当前最相似的三维点匹配即可，不要一次性把所有的点都放进 PnP 求解器。我的经验是每帧最多保留 500 个可靠匹配点，既保证位姿精度，又避免内存爆炸。
4.4 两张种子图的位姿估计方向错误，后续重建全崩
现象：程序没有报错，但重建出的相机轨迹和实际拍摄路径完全对不上，点云整体倒转或者镜像。
原因：三维重建存在尺度模糊性，本质上无法区分一个物体和它的放缩版本。如果种子对的三角化点深度为负，位姿就会被翻转。
解决：在三角化之后加一次深度检查，过滤掉深度为负的三维点。常见做法是计算三维点在两个相机坐标系下的深度，保留深度都大于零的点，同时用五点法或八点法解算出的本质矩阵来验证位姿的正负一致性。
4.5 点云数量远少于预估值，或只重建出几十个稀疏点
现象：所有代码运行完毕，但生成的点云总共只有不到 100 个点，看起来像一片稀稀拉拉的星空。
原因：图片重叠区域太小，或者相邻两张图的拍摄间距太大，导致特征匹配后的有效对应点过少。三角化需要至少两个视角的观测，如果视角变化过大，外极约束的不确定性就会扩散。
解决：拍摄时保证相邻两张图的重叠率不低于 70%，同时避免绕着一个物体做完整的 360 度旋转。SfM 更适合平移加小角度旋转的拍摄模式，而不是原地转圈。
5. 进阶玩法：用 Open3D 做稀疏点云可视化与 PLY 导出验证
跑通了基本流程之后，可以再往前走一步，把重建结果用 Open3D 可视化出来，顺便验证一下输出的sparse_points.ply是否真的符合三维重建的基本要求。这一步适合作为大作业的加分项。
Open3D 是一个非常适合做点云处理和可视化的 Python 库，安装很简单，读取 PLY 文件只需要几行代码：
import open3d as o3d # 读取 SfM 输出的稀疏点云 pcd = o3d.io.read_point_cloud("output/sparse_points.ply") # 获取点云中点的数量，判断输出是否正常 print(f"Point count: {len(pcd.points)}") # 可视化点云，支持鼠标拖拽旋转 o3d.visualization.draw_geometries([pcd])运行这段代码之后，你会看到一个由上千个彩色点组成的点云窗口，可以用鼠标旋转观察重建物体的大致轮廓。如果点云呈现清晰的连续表面，说明 SfM 的三角化质量不错；如果点云内部出现大量空洞和杂乱飞点，就需要回到第 4 章的避坑清单里逐项排查。
除了可视化，还可以做一道简单的验证题：把重建出的三维点投影回原始图像，检查重投影误差。这个操作能客观地判断位姿求解的精度，而不是只凭肉眼感觉。核心代码如下：
import numpy as np def compute_reprojection_error(points_3d, points_2d, rvec, tvec, camera_matrix): """ 计算一组三维点在当前相机位姿下的重投影误差 points_3d: (N, 3) 三维点 points_2d: (N, 2) 对应的二维观测 rvec: 旋转向量 (3, 1) tvec: 平移向量 (3, 1) camera_matrix: 相机内参矩阵 (3, 3) """ # 将三维点投影到二维 projected, _ = cv2.projectPoints( points_3d, rvec, tvec, camera_matrix, dist_coeffs=None ) projected = projected.reshape(-1, 2) # 计算均方根误差 error = np.sqrt(np.mean(np.sum((points_2d - projected) ** 2, axis=1))) return error这个函数的逻辑很直白：用你估计出的位姿把三维点重新投影到图像平面，计算投影点和原始二维观测之间的距离。误差在 1 像素以内说明位姿估计接近最优；超过 3 个像素就需要回去调调参数了。
从那以后，我每次跑完一组新数据，都会强制走一遍这个流程：先看点云数量，再打开 Open3D 看分布，最后算一遍重投影误差。三步都在合理区间，这份 SfM 代码才算真正跑出了令人信服的结果。希望帮到你。
本文还有配套的精品资源，点击获取
