1. 项目缘起当YOLOv5遇见深度相机大家好我是老张在AI和智能硬件这个圈子里摸爬滚打了十几年。今天想和大家聊聊一个特别有意思、也特别实用的实战项目把YOLOv5这个目标检测的“快枪手”和Intel RealSense D405这个能“看见”距离的深度相机撮合到一块儿。你可能已经用YOLOv5玩过不少目标检测了识别个猫猫狗狗、车辆行人都不在话下。但很多时候光知道“是什么”还不够我们还想知道“它离我有多远”。比如你想做个智能机器人让它不仅能认出面前的障碍物是椅子还是人还得知道椅子离它还有0.5米可以绕过去人离它还有2米需要减速。这时候单纯的2D图像信息就有点力不从心了。Intel的RealSense D系列深度相机特别是D405就是干这个的。它通过主动红外投射和双目成像原理能实时获取场景中每个像素点的深度信息也就是距离。而YOLOv5呢以其出色的速度和精度负责从彩色图像里把目标框出来。我们的目标就是把这两者的优势结合起来用YOLOv5框出目标再用D405提供的深度图去读取目标框中心区域的深度值从而计算出目标到相机的实际距离。这个组合能玩的花样可就多了。除了刚才说的机器人避障还能用在物流仓储的体积测量、零售行业的客流分析统计人数并估算距离、甚至是一些简单的工业检测场景里。我自己的团队就用这套方案做过一个智能叉车辅助系统效果相当不错。听起来是不是挺酷但说实话把这两样东西无缝对接起来中间有不少细节需要注意一不留神就会掉坑里。网上能找到的代码片段往往比较零散或者隐藏着一些默认大家知道的“潜规则”。接下来我就结合我踩过的坑和实战经验手把手带你走通整个流程从环境搭建、代码解读到关键调试技巧保证让你看完就能动手做出来。2. 环境搭建与硬件连接工欲善其事必先利其器。第一步咱们得把软硬件环境给准备好。这个过程稍微有点繁琐但每一步都很关键我会尽量说清楚。2.1 硬件准备与驱动安装首先你需要一台Intel RealSense D405相机。D405是RealSense D400系列里比较新的一款它的基线两个红外摄像头之间的距离更短适合中近距离的高精度测量对于室内机器人、桌面级应用非常合适。用USB 3.0数据线把相机连接到你的电脑上。这里有个大坑务必使用原装线或者高质量的USB 3.0线劣质线缆会导致供电不足或数据传输不稳定表现出来的现象就是深度图闪烁、帧率极低甚至直接无法识别设备。我刚开始就图便宜用了根不知名的线调试了半天才发现是线的问题白白浪费好几个小时。接下来是驱动和SDK。Intel提供了官方的librealsense2SDK这是和相机通信的基石。最省心的安装方式是使用PyPIpip install pyrealsense2如果你需要更底层的控制或者进行C开发可以去Intel RealSense的GitHub仓库下载源码编译。但对于我们Python用户pip安装通常就够了。安装完成后可以运行一个简单的测试命令来验证相机是否被正确识别import pyrealsense2 as rs print(rs.context().query_devices())如果能看到设备信息比如“Intel RealSense D405”那就说明驱动和SDK安装成功了。2.2 YOLOv5环境配置YOLOv5的环境大家可能比较熟悉了但为了完整性我还是过一遍。我强烈建议使用Python虚拟环境如conda或venv来管理避免包版本冲突。# 克隆YOLOv5官方仓库这里以v6.0版本为例比较稳定 git clone https://github.com/ultralytics/yolov5.git cd yolov5 pip install -r requirements.txtrequirements.txt里会安装PyTorch、TorchVision等依赖。注意PyTorch的版本最好根据你的CUDA版本去官网选择安装命令以获得GPU加速。没有GPU的话用CPU版本也能跑只是速度会慢一些。环境装好后别忘了准备你的权重文件。你可以使用官方预训练的模型如yolov5s.pt但更推荐使用在自己业务场景数据上训练好的best.pt文件。因为预训练模型是在COCO数据集上训练的里面可能没有你需要的特定类别比如某种特殊的工业零件。训练YOLOv5本身是个大话题这里就不展开了假设你已经有了一个训练好的、效果不错的best.pt文件。2.3 关键依赖库盘点除了上面两个核心我们还会用到一些辅助库大部分在YOLOv5的requirements里已经包含了我单独列出来强调一下OpenCV (cv2): 用于图像的读取、显示、绘制框和文字。我们处理彩色图、深度图的可视化都靠它。NumPy: 数组操作的基础深度数据、图像数据在Python里基本都是NumPy数组。PyTorch (torch): YOLOv5的推理引擎。你可以用pip list检查一下这些包是否都已就位。环境准备好硬件连上咱们就可以开始写代码了。3. 核心代码解读与融合逻辑现在我们进入最核心的部分代码。我会把原始文章里的代码拆开揉碎了讲并补充很多它没提到但至关重要的细节。原始代码是一个很好的起点但有些地方可以优化有些坑需要提前预警。3.1 初始化相机与模型加载代码开头是导入库和初始化。这里有一个超级重要的点也是很多新手会栽跟头的地方就是图像通道的顺序。import pyrealsense2 as rs import numpy as np import cv2 import random import torch import time # 加载YOLOv5模型 model torch.hub.load(E:/yolo/yolov5-6.0, custom, pathrbest1.pt, sourcelocal) model.conf 0.8 # 设置置信度阈值torch.hub.load的第一个参数是你的YOLOv5仓库本地路径。sourcelocal告诉它从本地加载。model.conf是置信度阈值高于这个值的目标才会被检测出来。0.8是个比较严格的值可以减少误检但可能会漏掉一些不太确定的目标你可以根据实际效果调整。接下来初始化RealSense相机pipeline rs.pipeline() config rs.config() config.enable_stream(rs.stream.depth, 640, 480, rs.format.z16, 60) config.enable_stream(rs.stream.color, 640, 480, rs.format.bgr8, 60) pipeline.start(config)这里我们同时开启了深度流和彩色流分辨率都是640x480帧率60FPS。rs.format.z16表示深度数据是16位无符号整数单位是毫米rs.format.bgr8表示彩色图像是8位BGR格式。注意OpenCV默认的彩色图像通道顺序就是BGR所以这里我们直接配置为BGR8后面用OpenCV显示时就不用转换了。3.2 图像通道的“生死坑”现在我们来到了原始文章用三个感叹号强调的“生死坑”图像通道顺序。这是整个项目里最容易出错且出错后最难排查的一点。在循环中我们从相机获取一对对齐的深度帧和彩色帧frames pipeline.wait_for_frames() depth_frame frames.get_depth_frame() color_frame frames.get_color_frame() # 转换为NumPy数组 depth_image np.asanyarray(depth_frame.get_data()) # 形状(480, 640) 每个值是毫米为单位的深度 color_image np.asanyarray(color_frame.get_data()) # 形状(480, 640, 3) BGR顺序此时color_image是一个NumPy数组它的通道顺序是B, G, R。这是由rs.format.bgr8和OpenCV的惯例共同决定的。而YOLOv5模型在训练时输入的图片通道顺序通常是R, G, B这是绝大多数图像处理库和深度学习框架的默认顺序如PIL、PyTorch的TorchVision。如果你直接把BGR格式的color_image丢给YOLOv5模型相当于看到了颜色完全错乱的图片蓝色和红色通道互换识别效果自然会一塌糊涂甚至完全失效。所以必须在送入模型前进行通道转换# 将BGR转换为RGB img_for_yolo color_image[:, :, ::-1] # 或者使用 cv2.cvtColor(color_image, cv2.COLOR_BGR2RGB) results model(img_for_yolo)color_image[:, :, ::-1]这个切片操作意思是在第三个维度通道维上进行反转从而将B,G,R变成R,G,B。这是一行非常高效且常用的转换代码。请务必记住这个操作它值得被写进你的备忘录。3.3 深度数据与检测框的融合计算拿到YOLOv5的检测结果results后我们提取检测框信息。原始代码使用了results.pandas().xyxy[0].values这是YOLOv5一种方便的格式每一行是[x_min, y_min, x_max, y_max, confidence, class, name]。现在我们有了2D的检测框和一张深度图。最直观的想法是取检测框中心点的深度值作为该目标的距离。但这样做非常不稳定。因为深度相机在物体边缘、反光表面或远处噪声会比较大单点采样很可能采到一个异常值比如突然一个特别大或特别小的深度。原始代码里的get_mid_pos函数采用了一种更鲁棒的方法随机区域采样 中值滤波。def get_mid_pos(frame, box, depth_data, randnum): distance_list [] # 计算检测框的中心坐标 mid_pos [(box[0] box[2]) // 2, (box[1] box[3]) // 2] # 确定一个搜索范围取框宽高的较小值 min_val min(abs(box[2] - box[0]), abs(box[3] - box[1])) for i in range(randnum): # 在中心点周围一定范围内随机偏移 bias random.randint(-min_val // 4, min_val // 4) # 获取偏移后点的深度值 dist depth_data[int(mid_pos[1] bias), int(mid_pos[0] bias)] # 在图上标出这个采样点蓝色点便于调试 cv2.circle(frame, (int(mid_pos[0] bias), int(mid_pos[1] bias)), 4, (255, 0, 0), -1) if dist: # 过滤掉深度值为0的点无效点 distance_list.append(dist) distance_list np.array(distance_list) # 对采样到的深度值排序并取中间一部分例如24个点取中间12个求平均 distance_list np.sort(distance_list)[randnum // 2 - randnum // 4:randnum // 2 randnum // 4] return np.mean(distance_list)我来解释一下这个方法的精妙之处随机采样在目标框中心区域随机取多个点randnum个比如24个而不是只取中心一个点。这能避免单点噪声。范围控制采样范围限制在框宽高的1/4内确保我们采样的点仍然落在目标物体上而不是背景上。中值滤波对所有采样到的深度值排序后只取中间一部分比如24个点中的第6到第18个来计算平均值。这能有效剔除离群值Outliers比如突然出现的极大或极小深度。这个方法我实测下来非常有效测距结果稳定多了。dectshow函数则负责把检测框和计算出的距离画到图像上def dectshow(org_img, boxs, depth_data): img org_img.copy() for box in boxs: # 画检测框 cv2.rectangle(img, (int(box[0]), int(box[1])), (int(box[2]), int(box[3])), (0, 255, 0), 2) # 计算距离 dist get_mid_pos(org_img, box, depth_data, 24) # 在框上方显示类别和距离单位转换为米 cv2.putText(img, box[-1] str(dist / 1000)[:4] m, (int(box[0]), int(box[1])), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 0, 255), 2) cv2.imshow(dec_img, img)注意dist是从深度相机直接读出的值单位是毫米。除以1000就换算成了米。str(dist / 1000)[:4]是取前4位字符显示像“0.85m”这样的格式。在主循环里我们调用dectshow(color_image, boxs, depth_image)将原始的BGR彩色图、检测框和深度图数据传进去就能实时看到带距离的检测效果了。4. 深度数据处理与优化技巧用上了深度相机你就得接受它的“脾气”。深度图不是完美的它受环境光、物体材质、距离等因素影响很大。直接使用原始深度数据可能会遇到各种问题。这一部分我们来聊聊怎么把深度数据“收拾”得更干净、更可靠。4.1 理解深度图与无效值首先打印一下depth_image的形状和几个值看看print(depth_image.shape) # (480, 640) print(depth_image.dtype) # uint16 print(depth_image[240, 320]) # 中心点的深度值例如 1250 (表示1.25米)深度图是一个单通道的、uint16类型的数组。每个像素的值代表该点到相机的直线距离单位是毫米。值为0通常表示该点无法计算出有效的深度无效点。无效点产生的原因很多超出量程D405的有效范围大约是几厘米到几米、光线被吸收如黑色物体、表面反光太强如镜子、视角过于倾斜等。在我们的get_mid_pos函数里用if dist:过滤了0值这是一个基本的处理。但有时候无效值可能不是0而是一个明显超出合理范围的极大值。因此更健壮的做法是结合相机量程进行过滤# 假设D405的有效量程是0.1米到10米 MIN_DEPTH_MM 100 # 0.1米 MAX_DEPTH_MM 10000 # 10米 if MIN_DEPTH_MM dist MAX_DEPTH_MM: distance_list.append(dist)4.2 使用RealSense后处理滤波器librealsense2SDK提供了一系列实时的后处理滤波器可以在数据流层面直接改善深度图质量这比我们在Python层做处理要高效得多。强烈推荐在初始化管道后加上它们。# 在 pipeline.start(config) 之后 profile pipeline.get_active_profile() depth_sensor profile.get_device().first_depth_sensor() # 可选设置一些硬件参数如激光器功率D405是主动红外发射 # depth_sensor.set_option(rs.option.laser_power, 150) # 创建后处理滤波器 dec_filter rs.decimation_filter() # 下采样滤波可降低噪声 spat_filter rs.spatial_filter() # 空间平滑滤波 temp_filter rs.temporal_filter() # 时域滤波利用多帧信息 # 在主循环中对深度帧应用滤波器 frames pipeline.wait_for_frames() depth_frame frames.get_depth_frame() # 应用滤波器链 depth_frame dec_filter.process(depth_frame) depth_frame spat_filter.process(depth_frame) depth_frame temp_filter.process(depth_frame) color_frame frames.get_color_frame()Decimation Filter通过下采样来平滑图像并减少数据量对中远距离的噪声抑制效果不错。Spatial Filter经典的边缘保留平滑滤波能抹掉一些椒盐噪声。Temporal Filter这是效果最明显的之一。它利用历史帧的信息来稳定当前帧对于静态场景能极大减少深度值的抖动。对于缓慢移动的目标也有帮助。启用这些滤波器后你会发现深度图看起来干净多了测距的读数也会稳定不少。每个滤波器都有参数可以调整一般用默认值就挺好。4.3 深度图与彩色图的对齐我们之前假设深度图的某个像素(x, y)和彩色图的同一个像素(x, y)对应的是现实世界中的同一个点。但实际上深度相机和彩色相机是两个独立的传感器它们的光心位置不同存在视差。对于D405Intel已经做了硬件和软件上的对齐我们通过rs.align可以轻松实现软件对齐。# 在配置流之后启动管道之前创建对齐对象将深度图对齐到彩色图 align_to rs.stream.color align rs.align(align_to) # 在主循环中 frames pipeline.wait_for_frames() # 将对齐应用到获取的帧上 aligned_frames align.process(frames) # 再从对齐后的帧里获取深度帧和彩色帧 aligned_depth_frame aligned_frames.get_depth_frame() color_frame aligned_frames.get_color_frame()经过对齐后aligned_depth_frame的每个像素就严格对应于color_frame的同一像素了。这对于需要像素级对应的应用比如我们的目标框内测距非常重要能提高测距的准确性。不过对齐操作会消耗一定的计算资源。如果你的应用对帧率要求极高且目标距离较远视差影响小也可以尝试不用对齐但需要评估精度损失。5. 实战调试与性能提升代码跑起来了基础功能也有了但你可能还会遇到一些烦人的小问题或者觉得性能不够理想。这部分我分享一些调试经验和优化技巧。5.1 常见问题排查问题一检测框乱飞或者根本检测不到。首先检查通道转换90%的问题出在这里。确认你送给YOLOv5的图片是RGB格式。一个简单的检查方法用OpenCV的cv2.imshow显示一下color_imageBGR再显示一下img_for_yoloRGB。如果后者颜色明显发蓝比如人的皮肤变蓝说明转换反了应该用[:, :, ::-1]而不是[:, :, :]。检查模型置信度阈值model.conf设得太高如0.9可能会漏检设得太低如0.3会产生很多假阳性框。可以尝试调整到0.5-0.7之间。检查输入图片尺寸YOLOv5模型有默认的推理尺寸通常是640。虽然它能处理任意尺寸但非正方形或比例奇怪的图片可能影响效果。确保从相机出来的640x480图像直接输入是没问题的。问题二测距数值跳动很厉害。检查采样点数量get_mid_pos函数里的randnum参数。太少了比如5个抗噪声能力差太多了比如50个计算量大。我试下来16到32之间是个不错的平衡点。检查深度图质量把深度图用cv2.applyColorMap着色后显示出来原始代码里就有看看目标区域的深度图是否连续、平滑。如果噪声很大考虑开启上一节说的后处理滤波器。检查环境深度相机对光照和物体表面材质敏感。确保环境光线充足但不含强红外光如阳光直射避免检测纯黑、镜面或透明物体。问题三程序运行帧率很低。降低分辨率或帧率将config.enable_stream中的640x480改为320x240或将帧率从60降到30能显著减轻计算和传输压力。优化YOLOv5推理如果使用GPU确保PyTorch是CUDA版本。也可以尝试更小的YOLOv5模型如yolov5n.ptNano版本速度更快精度稍低。减少显示开销cv2.imshow是比较耗时的操作尤其是显示多个窗口。可以考虑降低显示帧率比如每处理3帧显示1帧。5.2 代码优化与功能扩展原始代码是一个很好的演示但在实际项目中我们可能需要更健壮、功能更丰富的代码。1. 将处理逻辑封装成类把相机初始化、模型加载、处理循环封装成一个类会让代码更清晰也方便管理状态。class YoloRealsenseFusion: def __init__(self, model_path, conf_thres0.5): self.model self.load_model(model_path, conf_thres) self.pipeline, self.align self.init_camera() self.depth_filter self.init_filters() def load_model(self, path, conf): # ... 模型加载代码 pass def init_camera(self): # ... 相机初始化与对齐设置 pass def init_filters(self): # ... 初始化深度滤波器 pass def get_frame_and_detect(self): # ... 获取帧对齐推理 pass def calculate_distance(self, box, depth_map): # ... 改进版的测距函数 pass def run(self): # ... 主循环 pass2. 改进测距算法除了随机采样还可以考虑用检测框内所有有效深度点的中位数或均值或者先对深度图做一个小区域的形态学操作如闭运算填充空洞再计算。3. 增加更多输出信息比如在画框的同时把目标的像素坐标、实际物理尺寸如果知道的话也计算并显示出来。甚至可以加入简单的跟踪算法给同一个目标分配ID并记录其运动轨迹和速度需要结合多帧的3D位置。4. 处理多目标与遮挡当多个目标重叠时简单的框中心测距可能会采到错误目标的深度。一个改进思路是利用深度信息辅助区分重叠目标。例如比较两个检测框内深度值的分布如果差异明显则可能是前后遮挡的两个物体。调试这类项目耐心和观察力很重要。多利用OpenCV的显示功能把中间过程如采样点、深度图可视化出来能帮你快速定位问题所在。从能跑到跑得稳、跑得好中间还有一段路要走但每解决一个问题你对整个系统的理解就会加深一层。