风格相机

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

本项目是一个基于 Quectel Pi M2 智能主控板实现的 AI 风格相机示例。

系统通过 USB 摄像头采集实时画面，在板端 NPU 上运行艺术风格迁移模型与人体姿态模型，提供 11 种实时特效——宫崎骏风、油画、糖果、玻璃马赛克、素描、浮世绘、水墨画 7 种艺术风格，以及狗头、猪头、兔头、小丑头 4 种基于人体关键点定位的趣味贴纸，完整展示"视频采集 → NPU 实时风格化 → 一键拍照存储"的端到端链路。图形界面实时预览特效画面，按空格键即可保存风格化照片，并可从缩略图一键打开照片目录。

../../../_images/image_LPplbzAz9owhNPxROcscmpNWnRe.webp

开发资源汇总

开发配件清单

Note: tips

开发配件只是作为参考，不同的开发环境可能会有所差异

配件名称

数量

规格参数

Quectel Pi M2 智能主控板

1 块

-

USB 摄像头

1 个

UVC 协议，支持 720p MJPG

HDMI 显示器（可选）

1 个

有 HDMI 显示器也可，无屏可运行无界面模式

网线

1 根

用于 SSH 登录与代码拉取

Type-C 电源适配器

1 个

主控板供电

螺丝刀

若干

-

配件实物参考

../../../_images/image_XZy8bpQtVoonn0xR5ohcV3i2nIc.webp

快速上手

开发准备

Quectel Pi M2 智能主控板出厂默认搭载 Debian 13 系统镜像，因此无需再次烧录镜像，仅需按照如下步骤操作即可。NPU 运行时库、Python 3.12 环境及全部依赖由仓库自带的一键部署脚本自动完成安装。

硬件连接

完成以下所有硬件连接操作：

  1. 摄像头连接：将 USB 摄像头接入主控板 USB-A 口。可用 v4l2-ctl --list-devices 确认设备序号（示例机型为 PC Camera = /dev/video73），与配置不符时可用 --camera N 参数覆盖。

  2. 显示连接（可选）：接入 HDMI 显示器用于本地查看图形界面；无显示器时可运行无界面（Headless）模式。

  3. 网络连接：接入网线，用于 SSH 登录与代码拉取。

  4. 供电：连接 Type-C 电源上电。

Note: tips

本项目不需要麦克风、扬声器等音频外设。连接完成后可用 v4l2-ctl --list-devices 验证摄像头在位，或运行 --test-camera 实测采帧帧率。

项目实现

获取代码

在智能主控板上打开终端，使用 git 克隆项目代码。

sudo apt update
sudo apt install -y git
git clone https://github.com/Quectel-Pi/demo_style_camera.git
cd demo_style_camera

执行完成后，进入 style_cam_demo 目录，该目录即为本项目的全部源码。

环境部署

运行仓库自带的一键部署脚本，自动完成 Python 3.12 独立环境、推理依赖、RKNN 运行时库的安装：

sudo bash deploy/board_setup.sh

脚本支持 在线/离线双模式：在线模式下通过 uv 自动安装 Python 3.12 与 pip 依赖；离线模式下使用随包分发的 wheels 与 Python 离线包。同时会将 NPU 运行时 librknnrt.so 安装至系统目录。

Note: tips

板端依赖均安装于部署脚本创建的 /opt/py312 独立环境，请勿直接使用系统自带 python3 运行本项目（会报 ModuleNotFoundError）；run.sh 会自动定位该环境，日常运行一律通过 run.sh 启动。

自检测试

首次运行前建议依次执行内置自检，确认软硬件链路正常：

/opt/py312/bin/python3.12 selftest.py    # 离线自测: 模型加载/特效处理链路, 无需摄像头
sudo ./run.sh --test-camera              # 摄像头测试: 实测采帧帧率 5 秒
sudo ./run.sh --list-styles              # 列出当前可用的全部特效
sudo ./run.sh --test-style any.jpg       # 用任意一张静态图跑一遍全部特效并保存结果

运行程序

sudo ./run.sh

run.sh 会自动定位部署目录与 Python 环境、补全桌面显示授权后启动程序。若程序正常启动，会弹出"风格相机"窗口，左侧为特效实时预览画面，右侧为特效选择面板。

无显示器场景可运行无界面模式：

sudo ./run.sh --no-ui

界面与功能

程序正常运行后，预览默认为原始画面（约 25fps）；点击右侧特效按钮即可实时切换特效，按空格键拍照。

界面元素

功能说明

实时预览（左侧）

当前特效的画面预览，切换特效即时生效，拍照时白色闪光动画

状态栏

显示当前模式、实时帧率与单帧耗时

"风格特效"按钮组

宫崎骏风 / 油画 / 糖果 / 玻璃马赛克 / 素描 / 浮世绘 / 水墨画

"趣味贴纸"按钮组

狗头 / 猪头 / 兔头 / 小丑头，自动跟随人脸位置

拍照按钮（空格）

保存当前风格化画面为照片

缩略图

显示最近一张照片，点击打开照片目录

照片计数

统计本次运行已保存的照片数量

快捷键：图形界面下空格拍照；OpenCV 回退窗口下空格拍照、s 循环切换特效、q 退出。

特效一览

全部特效均运行在 NPU 上（模型文件缺失时对应模式自动隐藏）：

特效

风格来源

板端实测耗时

实测帧率

原始预览

-

-

约 25 fps（1280x720）

素描 sketch

CycleGAN photo2sketch

43 ms

17.1 fps

糖果 candy

fast-neural-style

62~66 ms

11.6~12.6 fps

玻璃马赛克 mosaic

fast-neural-style

62~66 ms

11.6~12.6 fps

油画 oil

fast-neural-style rain-princess

88 ms

9.1 fps

宫崎骏风 hayao

CartoonGAN

118 ms

6.7 fps

浮世绘 ukiyoe

CycleGAN

约 152 ms

约 5.5 fps

水墨画 ink

CIPGAN

约 152 ms

约 5.5 fps

狗头 / 猪头 / 兔头 / 小丑头

人体关键点贴纸

52~58 ms

14 fps 以上

拍照存储

按空格拍照后，照片自动保存至 photos/ 目录：

  • style_YYYYMMDD_HHMMSS.jpg：风格化后的画面（JPEG 质量 95）；

  • orig_时间戳.jpg：同时保存的原始分辨率原图（config.yaml 中 save.save_original: true 时启用）。

拍照通过独立存图线程 + 队列完成，不阻塞预览。

工作原理

系统数据流：摄像头 720p@30fps MJPG 采集 → 风格化线程（艺术风格模式：图像缩放至模型输入尺寸后送 NPU 推理，结果回贴原帧；贴纸模式：YOLOv8-Pose 检测人脸关键点，将贴纸 PNG 按关键点位置缩放贴合）→ UI 线程预览显示 / 拍照线程入队存图。

三个线程（取流风格化、存图、UI）相互解耦：预览始终流畅，拍照不卡顿。艺术风格迁移模型输入尺寸统一为 192×192（油画 224、宫崎骏风 160），归一化参数已写入 RKNN 模型，板端直接输入 RGB 图像即可。

模型文件位于 models/ 目录（7 个风格迁移模型 + 1 个姿态模型，均为 RK3576 NPU fp16 格式）；如需自行转换或替换风格模型，可参考 tools/ 目录下的转换脚本。

应用演示

style_cam_demo

常见问题及解决方案

程序找不到摄像头

现象：

Camera open failed

解决方案：

  • 使用命令确认摄像头设备号：v4l2-ctl --list-devices；

  • 修改 config.yaml 中 camera.index，或运行时用 --camera N 参数指定（本项目示例机型为 73）。

特效按钮缺失 / 提示模式不可用

现象：界面上某个特效按钮没有出现。

解决方案：

  • 对应特效的 RKNN 模型文件缺失时会自动隐藏该模式，检查 models/ 目录下对应 .rknn 文件是否完整（git clone 不完整或被清理）；

  • 运行 sudo ./run.sh --list-styles 查看当前实际可用的特效列表。

图形界面无法启动

现象：桌面环境下运行后无窗口弹出，程序回退到命令行模式。

解决方案：

  • 确认通过 sudo ./run.sh 启动，脚本已自动处理 Wayland 桌面下的显示授权（DISPLAY / XAUTHORITY / QT_QPA_PLATFORM）；

  • 若日志提示 Qt xcb 插件加载失败，安装缺失的系统库：sudo apt install -y libxcb-cursor0（部署脚本已内置自动安装兜底）；

  • 无显示器场景请直接使用 sudo ./run.sh --no-ui。

NPU 推理报错或模型加载失败

现象：

RKNN run error / librknnrt version mismatch

解决方案：

  • 确认 librknnrt.so 与板端 rknn-toolkit-lite2 版本匹配（重新执行部署脚本可自动对齐）；

  • 确认模型文件为 RK3576 目标平台编译的 .rknn（项目 models/ 目录自带）；

  • PC 上调试时可运行 python3 main.py --config config_onnx_debug.yaml --test-style any.jpg 走 CPU 推理验证链路。

技术支持与贡献

如在使用过程中遇到问题，欢迎在移远官方论坛提交技术咨询，我们的技术支持团队将及时为您解答。

项目开源地址： https://github.com/Quectel-Pi/demo_style_camera

欢迎提交 Issue 反馈问题或 Pull Request 贡献代码改进！