RK3588 开发板 Ubuntu 系统搭建与 OpenCV 环境部署要点

核心结论：系统自带 apt 包简单但无 MPP 硬件解码、RGA 不内置；源码编译可控，推荐 OpenCV 4.5~4.9，不要盲目上 5.x；RK3588 的硬件编解、YUV 缩放由 MPP/RGA 承担，OpenCV 只做 BGR 逻辑处理。

一、Ubuntu 系统前置检查（最容易踩坑）

1. 固件 / 内核版本优先

必须用厂商适配 RK3588 的 Ubuntu 镜像（Firefly / Armsom / Radxa），主线内核对 rga、mpp、drm、v4l2 mmap 支持不全；优先 5.10 内核，6.x 部分厂商 MPP 驱动适配差。

uname -a

ls /dev/rga /dev/mpp_service /dev/video0

缺少 /dev/rga 则 RGA 无法使用，很多图像 resize、格式转换只能 CPU 跑，帧率暴跌。

2. 架构确认 aarch64

arch  # 输出 aarch64

3. 源与基础依赖

sudo apt update

sudo apt install build-essential cmake git pkg-config libgtk-3-dev \

libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libxvidcore-dev \

libx264-dev libjpeg-dev libpng-dev libtiff-dev gfortran openexr \

libatlas-base-dev python3-dev python3-numpy libtbb2 libtbb-dev libdc1394-22-dev

Python 注意：板子原生 pip 的 opencv-python 预编译 wheel 大多是纯 CPU 版本，不支持 RK MPP 硬解，仅适合调试，不适合正式视觉管线。

二、三种安装方式对比

RKNN 官方示例配套一般是 OpenCV 4.5.5 / 4.6.0，和 rknn_api 兼容性最好，太高版本容易出现 dnn 模块、内存接口兼容问题。

三、源码编译关键 CMake 参数（RK3588 专属重点）

cmake -D CMAKE_BUILD_TYPE=Release \

-D CMAKE_INSTALL_PREFIX=/usr/local/opencv460 \

-D OPENCV_GENERATE_PKGCONFIG=ON \

-D BUILD_EXAMPLES=OFF \

-D BUILD_TESTS=OFF \

-D BUILD_PERF_TESTS=OFF \

-D BUILD_opencv_world=ON \

-D WITH_CUDA=OFF \

-D WITH_VTK=OFF \

-D WITH_QT=OFF \

-D WITH_GTK=ON \

-D WITH_FFMPEG=ON \

-D WITH_OPENCL=ON \

-D OPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules \

..

重点开关解释：

WITH_FFMPEG=ON：对接 ffmpeg，如果装了 ffmpeg-rockchip，OpenCV 的 VideoCapture 就可以走 rkmpp 硬件解码（普通 ffmpeg 还是软解）。

WITH_OPENCL=ON：RK3588 Mali GPU OpenCL 加速（注意：Mali OpenCL 不稳定，部分版本 bug 多，生产环境常关闭，交给 RGA）。

BUILD_opencv_world=ON：打包成单个 libopencv_world.so，部署拷贝更简单。

不要开启 WITH_VULKAN：RK3588 Mali + OpenCV vulkan 适配坑很多。

编译安装后，配置动态链接：

echo "/usr/local/opencv460/lib" | sudo tee /etc/ld.so.conf.d/opencv.conf

sudo ldconfig

# 验证

pkg-config --modversion opencv4

python3 -c "import cv2; print(cv2.__version__)"

四、RK 硬件加速：OpenCV + RGA / MPP 协作（重中之重）

OpenCV 原生不直接调用 RGA！OpenCV 没有 RGA 绑定，很多新手误区：以为编译 OpenCV 就能硬件 resize、NV12 转 BGR。

正确管线：

1. V4L2 摄像头输出 NV12(YUV) → RGA 做 NV12→BGR、resize、crop（DMA 零拷贝，几乎 0 CPU） → 传给 OpenCV Mat 做检测、绘图；

2. 或者 RTSP / 视频流 → ffmpeg-rockchip(rkmpp 硬解) → RGA 格式转换 → OpenCV Mat → RKNN 推理。

先编译官方 librga.so，放在系统库路径；编译程序时链接 -lrga。

摄像头拿到 dma buffer / fd，RGA 直接操作 fd，避免内存拷贝；如果把 YUV 拷贝到 CPU 内存再转 BGR，加速收益直接没了。

VideoCapture 硬解方案：编译 ffmpeg-rockchip（开启 --enable-rkmpp --enable-rkrga），OpenCV WITH_FFMPEG=ON，cv2.VideoCapture("rtsp://xxx") 底层走 MPP 硬解。

坑：原生 ffmpeg 不包含 rkmpp 解码器，apt 的 ffmpeg 一定是软解。

五、Python OpenCV 部署要点

源码编译时开启 BUILD_opencv_python3=ON，生成 .so 放到 python 的 site-packages，比 pip 包可控。

不要混用两套 OpenCV：系统 apt 的 opencv4 和源码编译版共存，import cv2 版本错乱。

多进程视觉服务：cv2.VideoCapture 在多进程里容易崩溃，建议单进程拉流 + RGA 预处理，队列分发图像。

内存：RK3588 内存不大（4G / 8G），高分辨率视频（1080P / 4K）不要用 cv2.imread/imwrite 高频读写，优先内存 buffer。

六、和 RKNN 联合部署（最常用场景）

RKNN 推理输入一般是 RGB / NV12，优先 RGA 预处理，不要用 cv2.resize / cvtColor（CPU 很慢）。

推荐流程：V4L2 → RGA → 输出推理输入格式 → rknn_infer → OpenCV 绘制框、保存图片、推流。

CMakeLists 写法：同时 find_package(OpenCV) + link librga + rknn_api。

版本匹配：rknn_toolkit2 版本、rknn_api 版本、OpenCV 版本固定，跨版本容易内存异常、推理卡死。

七、高频问题 & 避坑清单

1. cv2.VideoCapture 打不开摄像头：权限、/dev/video 权限、v4l2 驱动是否支持 mmap；RK 摄像头很多输出 NV12，原生 OpenCV 直接读容易花屏（缺少 RGA 转换）。

2. 编译 OpenCV 卡死、板子重启：不要 make -j$(nproc) 满核编译，RK3588 发热大，建议 -j4。

3. OpenCL 跑起来反而更慢：Mali 驱动版本问题，直接关闭 WITH_OPENCL=OFF，交给 RGA。

4. 内存泄漏：cv::Mat 没有 release、RGA buffer 没有 release fd；长期跑流服务必须做内存监控。

5. 跨板迁移：编译好的 OpenCV 库，只能在同内核、同 Ubuntu 版本 aarch64 上用，不同厂商固件不能直接拷贝 so。

八、最简验证脚本

import cv2

print(cv2.__version__)

cap = cv2.VideoCapture(0, cv2.CAP_V4L2)

cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)

cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)

ret, frame = cap.read()

if ret:

    print("image shape:", frame.shape)

cap.release()

这个脚本只是验证采集；真正低延迟方案要把 CAP_V4L2 拿到的 YUV 交给 RGA，而不是让 OpenCV 做 YUV 转码。

补充：生产环境推荐路线

Ubuntu(厂商 5.10) → 编译 ffmpeg-rockchip(MPP 硬解) → 编译 librga → 源码编译 OpenCV 4.6(WITH_FFMPEG=ON, OPENCL 关闭) → 视觉管线：RGA 预处理 + OpenCV 绘图 + RKNN 推理。

家具美容培训

家具维修培训