树莓派PiCamera工作正常但cv2.imshow无视频画面输出问题排查

问题描述 #

本周五摄像头还可正常使用，今日开机后无法接收到显示画面。经确认摄像头硬件可正常工作（自研机器人可基于摄像头反馈做出响应，摄像头工作指示灯正常点亮），代码精简至最简版本后问题仍存在。
最简测试代码如下：

import math
from cv2 import findContours
from distance.HCSRO4Component import *
from drive.dcMotorIndu import *
import numpy as np
import cv2 as cv
from threading import *
import os
import time
import logging

try:
    from imutils.video.pivideostream import PiVideoStream
    import imutils
except ImportError:
    logging.warning("Couldn't import PiCamera, continuing wihout...")
    
camIsPi = True
# Check whether cam arg is Pi camera

rotation = 90
vs = PiVideoStream(rotation=rotation).start()
time.sleep(1)

cycleOn = True
while (cycleOn == True):
    # Capture frame-by-frame
    frame = vs.read()
    print(frame)
    #frame = imutils.resize(frame, width=400)                
    cv.imshow("Video capture (Final result)", frame)

已知测试结果：

• 代码中print(frame)可正常返回帧数据
• 调用cv.imshow()仅能打开显示窗口，无视频画面展示
• 已尝试操作：将sudo modprobe bcm2835-v4l2写入内核、反复切换树莓派配置中enable camera选项开关
• 执行vcgencmd get_camera返回结果为supported=1 detected=1

故障原因及对应修复方案 #

按出现概率从高到低排序：

1. 缺失cv.waitKey()调用（90%概率为该原因）
   cv.imshow()本身不会触发窗口的画面刷新逻辑，必须在每次调用imshow后执行waitKey函数，为HighGUI组件留出事件处理和画面渲染的时间，否则窗口只会创建空白初始界面，永远不会更新帧内容。
   修复方式：在cv.imshow代码行后添加如下代码，参数需传入大于0的整数（单位为毫秒，代表每帧等待的时长），传入0会导致程序阻塞在第一帧：

# 刷新窗口，按q键退出循环
if cv.waitKey(1) & 0xFF == ord('q'):
    cycleOn = False
    break

程序退出前记得添加资源释放代码，避免下次运行出现窗口异常：

vs.stop()
cv.destroyAllWindows()

2. 帧色彩空间不匹配
   PiCamera默认输出RGB色彩空间的帧数据，而OpenCV的imshow原生适配BGR格式，部分版本的imutils PiVideoStream不会自动做色彩空间转换，会导致窗口渲染全黑/无画面。
   修复方式：在imshow调用前添加色彩空间转换代码：

frame = cv.cvtColor(frame, cv.COLOR_RGB2BGR)

3. 桌面渲染环境异常
   如果是通过SSH远程连接树莓派运行代码、未正确配置X11转发，或是在无桌面环境的树莓派Lite系统下运行带GUI的OpenCV程序，会出现窗口可创建但无法渲染画面的问题。
   排查方式：直接在树莓派本地连接显示器、键鼠，进入原生桌面环境运行代码，不要通过远程连接启动程序；如果使用Lite版系统，需先安装完整桌面环境，或先跳过imshow，通过将帧写入本地图片的方式验证帧数据本身是否正常。

4. OpenCV版本兼容问题
   如果是通过pip单独安装的opencv-python，大概率和树莓派系统自带的GTK等GUI框架存在依赖兼容问题，导致渲染异常。
   修复方式：卸载pip安装的OpenCV版本，改用apt源安装系统预适配的版本：

pip uninstall opencv-python opencv-contrib-python -y
sudo apt update && sudo apt install python3-opencv -y

内容的提问来源于stack exchange，提问作者I try so hard but I cry harder