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