简介：面向计算机视觉与自动驾驶领域的3D目标检测实战资源，基于YOLO实时检测框架与深度估计算法，给出从二维检测扩展到三维空间定位的完整工程实现，适用于希望快速上手YOLO三维改写的工程师、研究人员及高校学生。资源压缩包共7个文件，以5个Python源码脚本为核心，涵盖相机参数加载、深度估计模型、检测模型、三维边界框工具及主运行入口，另含1份依赖清单和1份说明文档，整体仅20KB，轻量易部署、便于按需修改，特别适合作为算法原型验证的基础代码。已有118人学习下载。通过阅读和运行源码，可掌握YOLO与深度信息融合的关键流程，理解三维边界框输出、深度距离估计、相机内参使用与坐标系处理等要点；描述中涉及的模型训练与评估思路也可作为后续改进方向，在此基础上可针对自动驾驶、机器人导航、安全监控等场景继续调优扩展。
1. 3D目标检测怎么落地：一份 YOLO + 深度估计的完整可跑工程
在自动驾驶和机器人项目里，单纯把目标框在画面里框出来远远不够，你至少还得知道它离摄像头多远。这也是为什么近两年 3D目标检测 越来越被强调。但真正动手做 3D 检测的人都会遇到同一个难题：网上论文复现代码多，能跑通、能出 3D 框的工程少。这份基于 YOLO + 深度估计实现的 3D目标检测项目源码，走的是当下最务实的单目融合路线——用 YOLO 输出 2D 检测框，用深度估计网络输出逐像素深度，再通过相机内参把两者拼成一个带位置、尺寸、朝向的 3D 边界框。适合想快速拿到一版能跑通的完整 3D 检测流程、然后在上面换数据集、换检测器或者做工程优化的从业者，也适合刚入门想理解 2D 检测如何升级为 3D 的开发者。
2. YOLO 和深度估计怎么融合：为什么单目方案也能出三维框
2.1 核心链路拆解：2D 检测、单目深度、相机几何三个模块
3D 目标检测要输出的不是二维框，而是目标在三维空间中的位置和姿态。KITTI 数据集的 3D 标注是一个 7 维向量：中心点坐标 (x, y, z)、尺寸 (h, w, l)、偏航角 yaw。所以只要能把这三类信息估计出来，一个 3D 框就成立。
项目把这个问题拆成三个模块：detection_model.py 负责 2D 目标检测，拿到目标的类别和像素坐标框；depth_model.py 负责单目深度估计，输出一张与输入图像同分辨率的深度图；load_camera_params.py 负责相机内参加载，解决像素坐标和三维坐标之间的转换问题。三者共同配合，最后通过 bbox3d_utils.py 把二维框、深度值和相机内参算成 3D 框的 8 个角点。
这个设计的好处是解耦。你不用担心 YOLO 改版了整套代码要重写，因为 detection_model.py 把检测器封装成了一个黑匣子，输入图像，输出检测框。深度估计模型同理，MiDaS、DPT、ZoeDepth 这些主流单目深度模型都能被替换，只要输出格式是单通道深度图就行。我一般会先把每个模块单独跑通，再去看融合效果，因为一旦输出结果出问题，分模块调试要比在整体流程里猜快得多。
2.2 坐标变换链路：像素坐标到相机坐标的四步投影
3D 框的生成不是把深度值直接贴在 2D 框中心上了事，中间有几步几何变换。完整链路是：2D 框中心点 (u, v) → 归一化相机坐标 → 结合深度缩放为相机坐标 (X, Y, Z) → 结合偏航角和物体尺寸生成 3D 框角点→ 投影回图像用于可视化。每一步的物理意义都很清晰：YOLO 给了图像上的目标中心，但图像上的中心点只有在已知深度的情况下才能对应到三维空间中的真实位置。
这里有个细节要特别注意：单目深度估计输出的深度值，是被相机焦距归一化过的相对深度，不是直接的物理距离。踩过坑的人都懂，用 MiDaS 这类模型时，如果想要米制单位上的绝对距离，必须乘以一个尺度因子，这个尺度因子通常来自数据集的统计值或特殊先验。项目默认的深度模型输出是深度图，我在复现时建议先打印一下深度图的数值范围，确认是 0~1 还是 0~255，这决定了后面求 Z 值要不要先做归一化。
最后，相机内参是 3D 检测的地基。fx、fy 决定深度怎么映射到空间尺寸，cx、cy 决定深度投影到二维平面的位置是否偏移。很多人在 2D 目标检测上精度很高，一旦接 3D 就翻车，问题往往出在相机内参没配对：用了标定好的内参却忘了输入图像已经被 Resize 过，导致投影全是斜的。
2.3 为什么不直接回归 3D 框：融合方案的工程优势
直接用神经网络回归 3D 框的方案不是没有，比如早期基于单目图像的 3D 框直接回归方法，但它们需要昂贵的 3D 标注数据训练。而 YOLO + 深度估计的融合方案，2D 检测器可以用任何公开的 COCO 预训练权重，深度模型也有大量无监督预训练权重可用，两个模块各自成熟，组合成本低。
这个方案也更容易部署。大多数实际项目的场景是“已有 2D 检测能力，需要补一个距离估计”，那么把深度模块作为一个旁路接进去，改动量要比换成端到端的 3D 检测模型小得多。而且两个模块可以放在不同的计算设备上，2D 检测跑 GPU，深度估计在边缘设备上有时甚至可以用轻量模型。当然融合方案的精度上限确实低于用激光雷达生成的稠密深度，但胜在纯视觉、成本低、实时性可控。
3. 源码逐文件拆解：相机参数、深度模型和 3D 框是怎么拼起来的
3.1 load_camera_params.py：相机内参的读取与缩放
这个文件是很多人会忽略但最容易出错的部分。它的作用是把相机标定得到的参数文件读进内存，并且完成“图像缩放后的内参修正”。项目支持的标定文件格式一般是常见的相机参数文件格式，读取后存的参数包括 fx、fy、cx、cy 和一个缩放系数。
import numpy as np import json def load_camera_params(json_path, scale_x=1.0, scale_y=1.0): """ 读取相机内参，并按图像缩放比例修正 fx fy cx cy scale_x / scale_y: 当前图像宽度 / 原始标定图像宽度 """ with open(json_path, 'r') as f: calib = json.load(f) fx = calib['fx'] * scale_x fy = calib['fy'] * scale_y cx = calib['cx'] * scale_x cy = calib['cy'] * scale_y return {'fx': fx, 'fy': fy, 'cx': cx, 'cy': cy}这段代码的逻辑实际上做了两件事：读取参数和参数适配。其中 scale_x 的计算很关键——如果你的 YOLO 输入尺寸是 640×640，而标定图像的原始尺寸是 1920×1080，那 fx 必须按 640/1920 缩放。我建议在项目入口处打印内参矩阵，第一次运行就确认缩放后的 cx、cy 接近图像中心，这是排查投影偏移的最快方法。
3.2 detection_model.py 和 depth_model.py：两个黑匣子的接口设计
detection_model.py 封装了 YOLO 的检测流程。这个文件的设计重点是接口统一，它对外只暴露一个 infer 方法，输入是图像，输出是检测框列表，每个框包含类别、置信度、四个坐标。无论你用的是官方 YOLOv5 还是 YOLOv8，只要修改这个文件内部的加载逻辑，外部调用完全不用变。
depth_model.py 同理，封装了单目深度估计网络。常见的实现里会加载预训练的深度模型权重，把输入图像标准化后送入网络，输出是一张深度图。需要留意的是不同深度模型对输入尺寸的敏感度差异很大，MiDaS 在训练时用的归一化参数在推理时不应改动，否则深度图质量会明显下降。
def preprocess_depth_input(image, target_size=384): """深度模型的输入预处理：保持长宽比并填充到 target_size""" h, w = image.shape[:2] scale = target_size / max(h, w) new_w, new_h = int(w * scale), int(h * scale) resized = cv2.resize(image, (new_w, new_h)) canvas = np.zeros((target_size, target_size, 3), dtype=np.uint8) canvas[:new_h, :new_w] = resized return canvas, scale这段预处理做了三件事：等比例缩放、边缘零填充、返回 scale 供后续恢复坐标用。很多深度模型要求输入为正方形，但直接压扁会破坏物体的纵横比，影响深度估计精度，所以用等比例缩放加填充是更稳妥的做法。注意返回的 scale 在后续投影到 3D 框时要配合相机内参一起用，不能只处理深度图却忘了坐标对齐。
3.3 bbox3d_utils.py：从 2D 框到 3D 框的几何计算
这个文件是整套代码里最核心的部分，包含了从图像坐标反算三维坐标、根据尺寸和偏航角生成 3D 框角点的全部逻辑。它做的事情可以拆成四步：已知 2D 框的中心像素坐标 (u, v)，结合深度图在该位置采样得到的深度值 z，通过相机内参反算相机坐标系下的 (X, Y)；再结合物体类别对应的先验尺寸 (h, w, l) 和估计的偏航角 yaw，生成 3D 框的 8 个角点。
def compute_3d_box(center_uv, depth_value, K, obj_size, yaw): """ center_uv: 2D 框中心像素坐标 depth_value: 深度图在该点采样的深度 K: 相机内参字典 obj_size: 物体先验尺寸 [h, w, l] yaw: 偏航角 """ fx, fy, cx, cy = K['fx'], K['fy'], K['cx'], K['cy'] u, v = center_uv # 像素坐标 -> 归一化相机坐标 -> 米制相机坐标 x = (u - cx) * depth_value / fx y = (v - cy) * depth_value / fy z = depth_value h, w, l = obj_size corners = [] for kx in [-l/2, l/2]: for ky in [-h/2, h/2]: for kz in [-w/2, w/2]: # 偏航角旋转 + 平移到中心点 xr = kx * np.cos(yaw) - kz * np.sin(yaw) zr = kx * np.sin(yaw) + kz * np.cos(yaw) corners.append([x + xr, y + ky, z + zr]) return np.array(corners)这里的核心逻辑是坐标反算和旋转平移。坐标反算的公式就是把相机投影模型反过来用，(u - cx) / fx 把像素坐标转成归一化坐标，再乘深度就是物理坐标。偏航角的旋转只绕 Y 轴（相机坐标系的垂直轴），因为车辆在地面上行驶时翻滚和俯仰角相对较小，可以忽略。这个假设在 KITTI 数据集上成立，但不适用于无人机视角，如果你换场景，需要在 rotate 部分加入俯仰角。
深度采样也是不能忽略的细节：直接取 2D 框中心点的单个像素，一旦中心点落在目标的空洞区域（比如车窗玻璃或车头格栅），深度值就会失真。建议在实现时取中心点周围半径为 5 的像素的深度中位数，同时因为深度估计网络输出的点云在目标边缘误差较大，乘上 1.05 到 1.1 的膨胀系数能显著改善可视化效果。
3.4 run.py 主流程：推理、后处理、可视化的一条龙
run.py 把前面所有模块串成完整的检测流程。主流程的思路很直白：读图 → 加载相机参数和模型 → YOLO 检测出 2D 框 → 深度估计出深度图 → 逐框计算 3D 框 → 在图像上绘制结果。但主流程里有两个配置参数值得展开讲，一个是置信度阈值，一个是目标类别过滤。
YOLO 默认的置信度阈值是 0.25，但在融合 3D 检测时，我通常会把它调高到 0.4 到 0.5。原因是单目深度估计在边缘和模糊区域的误差本来就大，低置信度的检测框一旦被用于三维重建，误差会被放大，导致画出来的 3D 框在地面上乱飘。在项目中如果想调整这个阈值，直接找到 run.py 里传给 detect 函数的 conf_thres 参数即可。类别过滤也很重要：如果项目只需要检测车和行人，就只保留对应类别 ID，避免路标、路灯这类物体对深度模块造成干扰。
python run.py --image test.png --calib data/calib.json这是一个最简单的运行命令。建议第一次运行不接摄像头，先拿单张图片跑通，然后逐步换视频流。项目 README 里对依赖项和运行步骤的说明比较清楚，requirements.txt 里的版本号建议不要随便升级，尤其是 torch 和 numpy 的版本——深度模型对 numpy 版本很敏感，升级容易导致 API 不兼容。
4. 运行排查：五个实际会撞上的坑
4.1 3D 框在图像上是斜的，偏移方向一致
现象：画出来的 3D 框虽然有立体感，但整体向一个方向倾斜，比如所有框都往右偏下。原因：输入图像被 Resize 到 YOLO 输入尺寸，但 load_camera_params.py 里的 scale_x/scale_y 默认值用了 1.0。解决：在加载内参时传入实际缩放比，即当前图像宽除以标定原图宽，cx、cy 同时缩放，重新运行后框就正了。这是最常见的坑，多数情况下是内参没做缩放导致的。
4.2 深度图看起来是反的，近处暗远处亮
现象：深度图输出颜色和预期相反，近处物体在图上显示为黑色。原因：很多深度模型输出的是视差值而非实际深度，视差与深度成反比，视差大说明距离近，但直接当深度用就反了。解决：在 depth_model.py 的后处理里对输出做一次反转：depth = 1.0 / (disp + 1e-6)。这一步不放进去会让 3D 框全部镜像。
4.3 3D 框在垂直方向上短一截
现象：检测框的 3D 投影高度明显小于实际物体，特别是车辆目标。原因：物体类别对应的先验尺寸 (h, w, l) 用了 KITTI 平均值，但深度估计的误差导致框的投影被压缩，而且我启用的是取中心点单个像素的深度值，中心点正好落在车窗上导致深度偏大。解决：把深度采样改成附近区域的中位数，同时对物体高度乘以 1.08 的修正系数。
4.4 画面很卡，视频流推理帧率很低
现象：在视频上跑推理，每帧要处理两百多毫秒，严重影响使用体验。原因：YOLO 检测和深度估计都跑在 CPU 上。解决：先在设备管理器里确认 GPU 推理可用。深度模型可以换成轻量版本，比如 MiDaS 的 small 版本，并把输入尺寸从 384 降到 256，深度质量损失不明显但速度接近翻倍。同样帧间可以只隔 1 帧跑一次深度估计，另一帧复用之前的深度图，因为相邻帧深度变化极小。
4.5 YOLO 置信度设太高导致目标漏检
现象：远处的行人和车辆完全检测不到，3D 检测结果稀疏。原因：conf_thres 设置过高，配合深度模型的目标中心遮挡情况漏检。解决：把置信度阈值降回 0.3，同时把类别的 NMS 阈值适当放宽。修改检测模型封装时，注意传入输出尺寸是否与原图匹配，不匹配的检测框在画 3D 投影时会整体错位，这其实是 NMS 之后没有把坐标乘回原图尺度，一并在后处理里修正。
5. 进阶：把单帧检测扩展成实时连续的视频流
项目默认跑的是单张图片，但实际工程场景里视频流才是常态。扩展思路不复杂：把图片加载换成摄像头的帧读取，但要做三件事才能保证体验稳定。第一是帧间降采样——不必每一帧都跑完整推理，2D 检测可以每帧跑，而深度估计隔 1 到 2 帧跑一次，中间帧沿用上一帧的深度图。第二是深度平滑——连续帧的深度值不会突变，对每个目标维护一个深度队列，取队列均值作为当前结果。第三是目标追踪——如果你有 DeepSORT 之类的追踪模块，不同帧之间框的关联可以由追踪器完成，3D 框只负责输出空间位置即可。
关于深度平滑，我一般会在目标框中心深度上做一个滑动平均，窗口大小为 5 帧，接在深度采样后面。这样即便某一帧深度估计出现明显跳动，输出结果依然稳定。如果你在跑自动驾驶相关的测试，还可以同步记录每帧的时间戳，把检测结果输出成 KITTI 格式的 txt 文件，便于后处理或评测。为了验证精度，建议在输出 3D 框时保留距离字段，和毫米波雷达或激光点云数据做交叉对比。单目深度估计在 20 米内的相对误差通常能控制在 10% 以内，超过这个范围后深度值会明显发散，做工程应用时需要在代码里加一个距离阈值过滤掉过远目标。
这套工程我第一次跑通的时候，在单张图上看到 3D 框稳稳地罩住车辆，心里其实很没底，总觉得哪里还有隐藏的误差。后来我养成了一个习惯：拿到任何 3D 检测代码，第一件事就是用标定板或一辆车实际测量几个距离值，对比模型的输出。从那以后我每次接手新的机器视觉项目都会强制做一步“标定-推理-实测”三元对照，不匹配就回头检查内参缩放和深度归一化。这套流程帮我在不少设备上避免了盲目调参。希望帮到你。
本文还有配套的精品资源，点击获取
