简介这份资源面向计算机视觉、三维重建方向的学习者与毕业设计开发者提供一套基于NeRF、用手机拍摄物体图片即可完成三维重建的Python工程。包内包含可本地编译运行的源码、配套数据集与文档说明评审分达95分以上难度适中适合作为课程实践、毕业设计或算法入门项目。压缩包共31个文件约5.37MB以21个py源码文件为核心辅以5个pyc编译文件、2个txt说明、1个md文档及gif、jpg演示素材覆盖数据加载、位姿估计、渲染路径生成、可视化与HTML导出等模块并集成COLMAP相关工具脚本。已有196人学习关注。读者可据此掌握从手机多视角照片到NeRF训练、渲染与结果展示的完整流程理解LLFF、DTU等数据组织方式并借助现成脚本快速复现实验、排查环境依赖问题节省自行搭建工程的时间。1. 手机拍一圈照片就能建模NeRF 三维重建到底能不能落地你拿手机围着一个杯子、一双鞋或者一件手办拍上三四十张照片丢进一段 Python 脚本里跑几个小时就能得到一个可以任意角度旋转查看的三维模型——这件事在 NeRFNeural Radiance Fields神经辐射场出现之后从论文里的炫技变成了普通工程师也能复现的流程。它解决的核心问题是传统摄影测量和结构光三维重建要么依赖昂贵的标定设备要么对反光、透明、弱纹理表面束手无策而 NeRF 用一组多视角图片加上隐式神经表示把「场景长什么样」直接学进一个多层感知机里渲染时按光线查询密度和颜色即可。这套「NeRF 手机拍摄 Python 源码 数据集 文档」的组合适合三类人想入门三维重建但买不起激光扫描仪的独立开发者、需要给电商商品做低成本 3D 展示的工程团队、以及拿它当毕业设计或课程作业的学生。下面我按自己踩过坑的顺序把从环境配置到训练出可用模型的完整路径讲清楚。2. 从手机照片到可训练数据集采集、清洗与坐标约定2.1 为什么手机拍摄的原始照片不能直接喂给 NeRFNeRF 的训练输入不是「一堆图片」而是「每张图片对应的相机位姿 内参」。手机相册里的 JPEG 只告诉你像素长什么样不告诉你拍摄时相机站在哪里、朝向哪个方向。所以第一步永远是把图片转成带位姿的数据集常见做法是用 COLMAP 做稀疏重建输出每张图的旋转矩阵、平移向量和焦距。这里有个反直觉的点照片数量不是越多越好。我试过用 120 张图重建一个马克杯结果比 40 张图还差原因是手机自动对焦导致不同帧的焦距轻微变化COLMAP 匹配时把这些帧当成不同相机位姿估计直接发散。所以采集阶段要锁死对焦和曝光宁可少拍、拍稳。采集时的具体约束我整理成一张表照着做能省掉后面大量返工采集参数推荐值不这样做的后果拍摄张数3060 张少于 20 张位姿解算失败率高环绕层数23 层高/中/低角度单层导致顶部和底部空洞重叠度相邻帧画面重叠 70% 以上重叠不足 COLMAP 匹配不上对焦/曝光手动锁定自动对焦让内参漂移背景纯色、无纹理干扰背景特征点抢走匹配资源光照均匀漫射光高光区域在 NeRF 里变成漂浮雾团2.2 用 COLMAP 生成 transforms.json 的完整命令NeRF 的 Python 实现无论是最早的 nerf-pytorch 还是后来的 instant-ngp 风格代码普遍读取一个transforms.json里面记录每张图的file_path、transform_matrix和相机camera_angle_x。这个文件不是 COLMAP 直接吐出来的需要中间转换。下面是我常用的流程先跑 COLMAP 命令行再用脚本转格式。# 1. 特征提取--ImageReader.single_camera 1 强制所有图共用内参 colmap feature_extractor \ --database_path ./colmap.db \ --image_path ./images \ --ImageReader.single_camera 1 \ --ImageReader.camera_model OPENCV # 2. 穷举匹配手机拍的小物体用 exhaustive_matcher 比 sequential 稳 colmap exhaustive_matcher --database_path ./colmap.db # 3. 稀疏重建输出到 sparse/0 colmap mapper \ --database_path ./colmap.db \ --image_path ./images \ --output_path ./sparse # 4. 导出为文本格式方便 Python 读取 colmap model_converter \ --input_path ./sparse/0 \ --output_path ./sparse/0 \ --output_type TXT这几条命令的逻辑是feature_extractor在每张图上找 SIFT 特征点并写进数据库exhaustive_matcher对所有图片两两匹配因为物体小、图片少穷举匹配比顺序匹配更不容易漏掉跨层视角mapper做增量式 SfM逐步加入图片并优化位姿最后model_converter把二进制模型转成cameras.txt、images.txt、points3D.txt三个文本文件。参数上最需要注意的是--ImageReader.single_camera 1它假设所有照片来自同一台相机、内参一致这正是手机拍摄场景该用的设置如果你混用了两台手机就得去掉这个参数并给每台相机单独标定。2.3 把 COLMAP 输出转成 NeRF 能读的 transforms.json拿到文本文件后用一段 Python 把四元数和平移向量拼成 4x4 变换矩阵并计算camera_angle_x。这段代码我改过很多次核心是坐标系转换COLMAP 是 Y 轴向下、Z 轴向前而 NeRF 的渲染代码通常假设相机看向 -Z所以要对矩阵做一次翻转。import numpy as np import json from pathlib import Path from scipy.spatial.transform import Rotation def colmap_to_nerf(images_txt, cameras_txt, out_json): # 读取相机内参取第一个相机的焦距 with open(cameras_txt) as f: cam_line f.readline().strip().split() width, height, fx float(cam_line[2]), float(cam_line[3]), float(cam_line[4]) camera_angle_x 2 * np.arctan(width / (2 * fx)) frames [] with open(images_txt) as f: lines [l.strip() for l in f if l.strip() and not l.startswith(#)] # images.txt 每两行描述一张图第一行是位姿第二行是特征点 for i in range(0, len(lines), 2): parts lines[i].split() qw, qx, qy, qz map(float, parts[1:5]) tx, ty, tz map(float, parts[5:8]) name parts[9] rot Rotation.from_quat([qx, qy, qz, qw]).as_matrix() # COLMAP 到 NeRF 的坐标轴翻转 flip np.diag([1, -1, -1]) rot flip rot trans flip np.array([tx, ty, tz]) mat np.eye(4) mat[:3, :3] rot mat[:3, 3] trans frames.append({file_path: f./images/{name}, transform_matrix: mat.tolist()}) with open(out_json, w) as f: json.dump({camera_angle_x: camera_angle_x, frames: frames}, f, indent2) colmap_to_nerf(./sparse/0/images.txt, ./sparse/0/cameras.txt, ./transforms.json)逻辑说明camera_angle_x是水平视场角NeRF 用它配合图片宽高算光线方向所以必须从 COLMAP 的焦距反推不能随便填。flip矩阵做的是把 COLMAP 的相机坐标系翻到 NeRF 约定这一步如果漏掉训练出来的模型会上下颠倒或者整个场景跑到相机背后。参数上Rotation.from_quat的输入顺序是[x, y, z, w]而 COLMAP 文本里是qw qx qy qz顺序写反是新手最常见的翻车点表现为渲染出来全是噪点。转换完打开transforms.json检查frames数量是否等于图片数少一张都说明images.txt解析有问题。3. 搭 NeRF 训练环境Python 依赖、CUDA 版本与显存估算3.1 依赖装不对后面全是玄学报错NeRF 的 Python 源码通常依赖 PyTorch、tiny-cuda-nn如果用的是 instant-ngp 系实现或者纯 PyTorch 的 MLP 版本。我一般先确认显卡驱动和 CUDA 版本再决定装哪个 PyTorch。用nvidia-smi看驱动支持的最高 CUDA 版本然后去 PyTorch 官网找对应命令。这里有个血泪经验不要用pip install torch不带版本号它可能给你装一个 CPU 版训练时 GPU 利用率一直是 0你还以为是代码问题。# 查看驱动和 CUDA 版本 nvidia-smi # 以 CUDA 11.8 为例装对应 PyTorch pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 验证 GPU 是否可用 python -c import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))如果输出True和你的显卡型号环境就通了。接着装numpy、scipy、imageio、opencv-python这些基础库。纯 PyTorch 版 NeRF 对显存的要求可以用公式粗估显存 ≈ 图片分辨率像素数 × 每批光线数 × 网络层数相关常数。实际经验是 1080p 图片、batch 1024 条光线8GB 显存能跑但要把N_rand调小4GB 显存基本只能降到 512×512 分辨率训练。3.2 训练命令与关键参数怎么改假设源码入口是run_nerf.py典型训练命令如下python run_nerf.py \ --config configs/lego.txt \ --datadir ./data/lego \ --basedir ./logs \ --expname my_object \ --N_rand 1024 \ --N_samples 64 \ --N_importance 128 \ --netdepth 8 \ --netwidth 256 \ --learning_rate 5e-4 \ --N_iters 200000参数含义逐个说N_rand是每次迭代随机采样的光线数直接决定显存占用和训练速度显存不够先降它N_samples是粗网络沿每条光线采的粗采样点数N_importance是细网络在粗采样高密度区域追加的点数这两个值越大细节越好但越慢netdepth和netwidth是 MLP 的层数和每层宽度8 层 256 宽是原论文配置物体小可以降到 6 层 128 宽learning_rate用 5e-4 比较稳调到 1e-3 容易发散。训练过程中看logs/my_object下的 loss 曲线正常情况前几千步 loss 快速下降之后缓慢收敛如果 loss 一直震荡先检查transforms.json里的位姿是不是错的。3.3 数据集目录该长什么样源码配套的数据集一般按场景分文件夹每个场景下放images/和transforms.json或者sparse/0/。我习惯的目录结构是data/ my_object/ images/ IMG_001.jpg IMG_002.jpg ... transforms.json如果拿到的是官方数据集比如 NeRF 论文的 lego、fern它可能已经包含transforms_train.json、transforms_val.json、transforms_test.json三个文件分别对应训练、验证、测试视角。自己拍的数据集只需要一个transforms.json训练脚本会自动按比例划分。注意图片路径在 json 里是相对路径跑训练时的工作目录要和 json 里的file_path前缀对得上否则报FileNotFoundError。4. 避坑与排查训练不收敛、渲染有雾、显存爆掉的真实原因4.1 训练几万步后画面还是糊的现象loss 降到某个值就不动了渲染出来像蒙了一层毛玻璃。原因通常是位姿精度不够或者光线采样范围不对。手机拍摄的图片如果 COLMAP 重投影误差大于 1 像素NeRF 会把误差学成模糊。解决办法是在 COLMAP 里开--Mapper.ba_global_function_tolerance1e-6做全局 BA 优化或者干脆用hloc这类更鲁棒的匹配流程重跑一遍。另一个原因是--near和--far参数设得离物体太远光线大部分采样点落在空区域密度网络学不到东西。我一般先量一下物体到相机的距离把near设成最近距离的 0.8 倍far设成最远距离的 1.2 倍。4.2 渲染结果里出现漂浮的彩色雾团现象旋转模型时能看到一些半透明的色块悬在空中。原因是训练图片里有高光或者背景纹理NeRF 把这些区域当成了真实几何。解决分两步采集时用偏振片或者柔光箱压掉高光训练时在transforms.json里给每张图加一个 mask把背景涂黑让 loss 只计算物体区域。很多源码支持--use_mask参数配合images_mask/目录使用。如果源码不支持 mask退而求其次是在 COLMAP 阶段用--ImageReader.mask_path指定掩码让特征点只落在物体上。4.3 显存爆掉但显卡明明够大现象报CUDA out of memory但nvidia-smi显示显存还有富余。原因通常是 PyTorch 缓存分配器碎片化或者N_rand设得太大导致单次前向传播就超了。先降N_rand到 512 试如果还爆在训练脚本开头加torch.cuda.empty_cache()并把--N_importance降到 64。还有一个隐蔽原因是图片分辨率没降源码默认读原图手机照片 4000×3000 直接进网络显存瞬间吃满。解决办法是在数据加载部分加 resize或者提前用ffmpeg把图片缩到 800×600。# 批量把图片缩到长边 800 像素 mkdir images_small for f in images/*.jpg; do ffmpeg -i $f -vf scalemin(800,iw):-1 images_small/$(basename $f) done4.4 训练完导出 mesh 全是碎片现象用 marching cubes 提取网格后模型是一堆不连通的碎片。原因是 NeRF 的密度场在物体表面附近不够锐利等值面提取时阈值选得不好。解决办法是训练时加--raw_noise_std 0.1让密度更平滑导出时把阈值从默认的 10 降到 5 左右并且用--N_grid 256提高采样网格分辨率。如果还是碎说明位姿本身有漂移回到 4.1 重新优化 COLMAP。4.5 换一台机器跑就报版本不兼容现象在自己电脑上跑通的代码换到服务器上报undefined symbol或者torch version mismatch。原因是 PyTorch、CUDA、tiny-cuda-nn 三者版本必须严格对应。我的习惯是用conda建独立环境把environment.yml导出里面锁死pytorch2.0.1py3.10_cuda11.8这种完整版本号。如果源码依赖 tiny-cuda-nn它需要和 CUDA 版本一起编译换机器必须重新pip install githttps://github.com/NVlabs/tiny-cuda-nn/#subdirectorybindings/torch不能直接拷贝编译好的.so文件。5. 进阶技巧用少样本和深度先验把重建时间压到半小时内原始 NeRF 要跑十几小时甚至几天这对想快速验证的工程师不友好。我后来固定用两条加速路线一是少样本训练把图片降到 20 张以内配合--N_iters 50000和更大的学习率半小时能出粗模二是引入深度先验用手机的人像模式或者单目深度估计模型如 MiDaS生成每张图的深度图作为额外监督信号加到 loss 里这样即使位姿有轻微误差深度也能把几何约束住。具体做法是在数据加载时多读一个depths/目录训练 loss 改成# 在原有 color loss 基础上加深度监督 color_loss ((rgb_pred - rgb_gt) ** 2).mean() depth_loss ((depth_pred - depth_gt) ** 2).mean() loss color_loss 0.1 * depth_loss权重 0.1 是我试出来的经验值太大导致颜色发灰太小起不到约束作用。深度图不需要很准MiDaS 输出的相对深度归一化到 [0,1] 就能用。这套组合让我在 RTX 3060 上把一个小物体的重建时间从 8 小时压到 40 分钟精度损失肉眼几乎看不出来。验证重建质量我一般看两个指标PSNR 和 LPIPS。PSNR 高于 25dB 说明颜色还原可以LPIPS 低于 0.1 说明感知质量接近真实。但指标只是参考最终还是要旋转模型看有没有空洞和漂浮物。我现在的习惯是每次采集完先跑一遍 COLMAP把重投影误差图存下来误差大的区域直接重拍而不是等 NeRF 训练完再返工。这个习惯帮我省掉了至少一半的无效训练时间。希望帮到你。本文还有配套的精品资源点击获取