# 风格相机

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

---

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

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

```{image} images/image_LPplbzAz9owhNPxROcscmpNWnRe.webp
:width: 1320px
:height: 672px
:align: center
```

## 开发资源汇总

### 开发配件清单

Note: tips

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

| **配件名称** | **数量** | **规格参数** |
| --- | --- | --- |
| Quectel Pi M2 智能主控板 | 1 块 | - |
| USB 摄像头 | 1 个 | UVC 协议，支持 720p MJPG |
| HDMI 显示器（可选） | 1 个 | 有 HDMI 显示器也可，无屏可运行无界面模式 |
| 网线 | 1 根 | 用于 SSH 登录与代码拉取 |
| Type-C 电源适配器 | 1 个 | 主控板供电 |
| 螺丝刀 | 若干 | - |

### 配件实物参考

```{image} images/image_XZy8bpQtVoonn0xR5ohcV3i2nIc.webp
:width: 1085px
:height: 189px
:align: center
```

## 快速上手

### 开发准备

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/` 目录下的转换脚本。

### 应用演示

<div class="video-preview">
  <video width="100%" controls preload="none">
    <source src="videos/video_UMaLbBdWxorHC0xL7TUcoWPEnY4.mp4" type="video/mp4">
    Your browser does not support the video tag.
  </video>
  <div class="video-caption">
    <strong>style_cam_demo</strong>
  </div>
</div>


## 常见问题及解决方案

### 程序找不到摄像头

现象：

```
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 贡献代码改进！