CV

面向 reComputer RK3576/RK3588 的计算机视觉应用指南。

支持的平台

平台	芯片	算力	镜像名称
RK3588	RK3588/RK3588S	6 TOPS	`rk3588-yolo`
RK3576	RK3576	6 TOPS	`rk3576-yolo`

快速开始

1. 安装 Docker

在开发板上运行以下命令安装 Docker:

bash

# 下载安装脚本
curl -fsSL https://get.docker.com -o get-docker.sh
# 使用阿里云镜像源安装
sudo sh get-docker.sh --mirror Aliyun
# 启动 Docker 并启用开机自启
sudo systemctl enable docker
sudo systemctl start docker

2. 运行项目(一条命令,双模式预览)

本项目同时支持 本地 GUI 与 浏览器 预览。程序会自动检测显示环境,如果未连接显示器则降级为 Web 模式。

步骤 A:配置显示权限(可选)

如果你已连接显示器且希望在本地查看窗口:

bash

xhost +local:docker

步骤 B:拉取镜像

bash

sudo docker pull ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3588-yolo:latest
sudo docker pull ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3576-yolo:latest

步骤 C:一键运行

RK3588:

bash

sudo docker run --rm --privileged --net=host \
    -e PYTHONUNBUFFERED=1 \
    -e RKNN_LOG_LEVEL=0 \
    --device /dev/video1:/dev/video1 \
    --device /dev/dri/renderD129:/dev/dri/renderD129 \
    -v /proc/device-tree/compatible:/proc/device-tree/compatible \
    ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3588-yolo:latest \
    python web_detection.py --model_path model/yolo11n.rknn --camera_id 1

RK3576:

bash

sudo docker run --rm --privileged --net=host \
    -e PYTHONUNBUFFERED=1 \
    -e RKNN_LOG_LEVEL=0 \
    --device /dev/video0:/dev/video0 \
    --device /dev/dri/renderD128:/dev/dri/renderD128 \
    -v /proc/device-tree/compatible:/proc/device-tree/compatible \
    ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3576-yolo:latest \
    python web_detection.py --model_path model/yolo11n.rknn --camera_id 0

通过 http://<Board_IP>:8000 访问。

注意:如果你需要自定义类别,可添加 -v $(pwd)/class_config.txt:/app/class_config.txt \ 挂载与 --class_path 参数。程序默认使用 COCO 80 类。

示例:

bash

sudo docker run --rm --privileged --net=host \
    -e PYTHONUNBUFFERED=1 \
    -e RKNN_LOG_LEVEL=0 \
    -v $(pwd)/class_config.txt:/app/class_config.txt \
    --device /dev/video1:/dev/video1 \
    --device /dev/dri/renderD129:/dev/dri/renderD129 \
    -v /proc/device-tree/compatible:/proc/device-tree/compatible \
    ghcr.io/Seeed-Projects/recomputer-rk-cv/rk3588-yolo:latest \
    python web_detection.py --model_path model/yolo11n.rknn --camera_id 1 --class_path class_config.txt

🔌 API 文档

本项目提供与 Ultralytics Cloud API 标准兼容的 RESTful 接口,支持通过 HTTP POST 上传图片进行目标检测。

1. 模型推理接口(Predict)

Endpoint: POST /api/models/yolo11/predict

请求参数(Multipart/Form-Data):

file:(可选)待检测的图像文件。
video:(可选)待检测的 MP4 视频文件。
timestamp:(可选)视频文件中的时间戳(秒),返回该时刻对应帧的检测结果。默认 0。
realtime:(可选)布尔值。当为 true,或未提供 file/video 参数时,返回当前摄像头帧的检测结果。
conf:(可选)单次请求的置信度阈值,范围 0.0-1.0。
iou:(可选)单次请求的 NMS IOU 阈值,范围 0.0-1.0。

使用示例:

1. 图像检测:

bash

curl -X POST "http://127.0.0.1:8000/api/models/yolo11/predict" -F "file=@/home/cat/001.jpg"

2. 视频指定帧检测:

bash

curl -X POST "http://127.0.0.1:8000/api/models/yolo11/predict" -F "video=@/home/cat/test.mp4" -F "timestamp=5.5"

3. 获取当前摄像头帧检测:

bash

curl -X POST "http://127.0.0.1:8000/api/models/yolo11/predict" -F "realtime=true"
# 或者不带 file 参数
curl -X POST "http://127.0.0.1:8000/api/models/yolo11/predict"

响应格式(JSON):

json

{
  "success": true,
  "source": "video frame at 5.5s",
  "predictions": [
    {
      "class": "person",
      "confidence": 0.92,
      "box": { "x1": 100, "y1": 200, "x2": 300, "y2": 500 }
    }
  ],
  "image": { "width": 1280, "height": 720 }
}

2. 系统配置接口(Config)

用于为实时视频流和默认推理动态调整阈值。

获取当前配置

端点: GET /api/config
响应: {"obj_thresh": 0.25, "nms_thresh": 0.45}

更新系统配置

端点: POST /api/config
请求体(JSON): {"obj_thresh": 0.3, "nms_thresh": 0.5}
响应: {"status": "success"}

3. 命令行参数

web_detection.py 支持以下参数:

参数	说明	默认值
`--model_path`	RKNN 模型文件路径	(必填)
`--camera_id`	摄像头设备 ID(例如,`/dev/video1` 填 1)	1
`--video_path`	视频文件路径(若提供则覆盖 camera_id)	None
`--class_path`	自定义类别配置文件(class_config.txt)路径	None(默认 COCO 80)
`--host`	Web 服务监听地址	`0.0.0.0`
`--port`	Web 服务端口	8000

自定义类别配置(class_config.txt)格式:

使用双引号命名类别,以逗号分隔,例如: "person", "bicycle", "car", "motorbike"

实时视频流接口(Video Feed)

获取叠加检测框的实时 MJPEG 视频流,可直接嵌入 HTML <img> 标签。

端点: GET /api/video_feed
使用示例: <img src="http://<Board_IP>:8000/api/video_feed">

各平台详细文档

自动化构建

本项目通过 GitHub Actions 支持多平台镜像的自动化构建。

修改 src/rk3588/ 目录会自动触发 rk3588-yolo 镜像构建。
修改 src/rk3576/ 目录会自动触发 rk3576-yolo 镜像构建。
也支持手动触发,可指定 image_tag。

🛠️ 开发者指南(生产环境建议)

代码说明

web_detection.py:
- 双模式支持:集成 FastAPI,同时支持本地渲染与 MJPEG 流输出。
- 环境自适应:自动检测 DISPLAY 环境变量,缺失时静默跳过 GUI 初始化。
- RKNN 推理:封装 RKNN 初始化、模型加载与多核推理逻辑。
- 动态加载:支持通过 --class_path 动态加载类别配置。
- 后处理:YOLOv11 专属的 Box 解码与 NMS 逻辑。

修改模型

将训练并转换好的 .rknn 模型放入对应平台的 model/ 目录。
在运行命令中添加 --model_path 参数指向新模型(Dockerfile 中已配置默认值)。

在 reComputer RK3576 上的实时 YOLOv11 目标检测演示

Previous配置

NextLLM