# 人脸变换
***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***
---
本文档介绍基于USB摄像头的人脸变换功能及使用方法。该功能通过云端接口实现人脸效果处理，并提供图形化交互界面，帮助用户快速部署与验证效果。完成环境准备、依赖安装和参数配置后，可在Quectel Pi M2智能主控板上运行项目，实现人脸变换效果并输出结果。
当前支持的核心功能：
- 人脸年龄变换：生成不同年龄段的人脸效果，并合成视频播放；
- 人像动漫化：将人像转换为动漫风格图片；
- 人脸性别转换：以整图方式生成单张人脸的性别转换结果。
此外，该项目支持自动识别并调用摄像头设备，同时输出运行状态与日志信息，便于用户查看运行进度及排查问题。
```{image} images/image_Jk1Ybkrado0hvYxdroMcqfglnad.webp
:width: 554px
:height: 346px
```
# 开发资源汇总
## 开发配件清单
|
配件名称
|
数量
|
规格参数
|
| --- | --- | --- |
| Quectel Pi M2智能主控板 |
1
| Quectel Pi M2智能主控板 |
| USB摄像头模块 |
1
| [绿联高清USB摄像头带麦克风(2K 400万高清自动对焦）]() |
| USB-C电源适配器 |
1
| [27W USB Type-C接口充电器1.2米线长中规电源PD电源适用于树莓派5代]() |
| CPU散热风扇(可选) |
1
| [树莓派5代官方原装散热器带导热贴]() |
| HDMI A 型对公线 |
1
| HDMI 2.0；线长1 m；接口：HDMI-A（公头）-HDMI-A（公头） |
| 网线 |
1
| 线长：1 m；传输速率：千兆 |
| 显示屏 |
1
| 24英寸HDMI显示器 |
## 配件实物参考
```{image} images/image_KHt2bjQqco8BsrxWYERcsg4Inoc.webp
:width: 1160px
:height: 688px
:align: center
```
# 快速上手
## 开发准备
**Quectel Pi M2智能主控板** 出厂预装 **Debian 13** 系统镜像，因此无需重新烧录系统镜像，按照以下步骤操作即可。
## 硬件连接
按照以下步骤完成所有硬件连接（步骤编号与接口示意图中的标注一致）：
```{image} images/image_PMabbZMgVoOTjbxPZPtcCfQtngc.webp
:width: 627px
:height: 463px
:align: center
```
1. **显示连接**：将HDMI线的一端连接到智能主控板的HDMI接口，另一端连接到显示器的HDMI接口。
2. **网络连接**：确保路由器已连接互联网，然后将网线的一端连接到智能主控板的千兆以太网端口，另一端连接到路由器的以太网端口。
3. **输入设备连接**：将USB键盘、鼠标和USB摄像头等输入设备连接到智能主控板的USB接口。如果使用无线输入设备，将无线接收器连接到扩展坞的USB接口即可。
4. **供电连接**：将USB-A电源线的USB-A端连接到电源适配器的输出端，将USB-C端连接到智能主控板的电源输入接口（通常标注为 **POWER IN**）。
## 项目实现
### 更新软件源
执行以下命令更新系统软件源：
```plaintext
sudo apt update
```
### 安装系统依赖
安装基础依赖包：
```plaintext
sudo apt install -y python3 python3-venv python3-pip ffmpeg git vim
```
安装图形界面相关依赖：
```plaintext
sudo apt install -y libxcb-cursor0 libxkbcommon-x11-0 \
libxcb-xinerama0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0
```
### 创建虚拟环境
新建项目目录：
```plaintext
mkdir -p ~/Project
```
进入项目目录并创建Python虚拟环境：
```plaintext
cd ~/Project
python3 -m venv .venv
```
### 激活虚拟环境
```plaintext
source ~/Project/.venv/bin/activate
```
### 下载示例代码
```plaintext
cd ~/Project
git clone https://github.com/Quectel-Pi/demo-face-transform.git
```
### 更新pip源
```plaintext
pip install --upgrade pip
```
### 安装项目依赖库
```plaintext
pip install -r requirements.txt
```
```{note}
请确保已激活虚拟环境，并在 *demo-face-transform* 目录下执行该命令（若路径不符，需调整 *requirements.txt* 路径）。
```
### 配置密钥
使用人脸变换服务前，需先开通腾讯云相关服务，并在腾讯云访问管理控制台获取API调用密钥（*SecretId* 和 *SecretKey*）。详情请参考 [腾讯云人像变换API文档]()。
**方式1**：通过环境变量读取密钥（示例）
```plaintext
export TENCENTCLOUD_SECRET_ID="SecretId"
export TENCENTCLOUD_SECRET_KEY="SecretKey"
```
**方式2**：通过启动脚本配置
编辑 **start.sh** 脚本，填入 *SecretId* 和 *SecretKey*。
### 运行程序
在 **start.sh** 中配置 *SecretId* 和 *SecretKey*:
```plaintext
cd demo-face-transform/src
chmod +x start.sh
./start.sh
```
### 图形界面远程运行配置
若需通过SSH远程会话运行图形界面程序，请完成以下配置：
1. 在设备本地桌面终端中执行权限配置命令：
```plaintext
xhost +SI:localuser:pi
```
该命令允许本地 *pi* 用户访问当前X11显示服务。
2. 在SSH远程会话中设置图形显示环境变量：
```plaintext
export DISPLAY=:0
export XAUTHORITY=/home/pi/.Xauthority
```
配置完成后，可在SSH会话中运行图形界面程序。
# 应用演示
face_transform
# 技术支持与贡献
如在使用过程中遇到问题，欢迎在 [移远官方论坛]() 提交技术咨询，我们的技术支持团队将及时为您解答。
项目开源地址：[https://github.com/Quectel-Pi/demo-face-transform]()
欢迎提交Issue反馈问题，或提交Pull Request改进代码。