人脸变换¶

本文档主要介绍基于USB摄像头的人脸变换功能及使用方法。该功能通过云端接口实现人脸效果处理，并提供图形化交互界面，帮助用户快速部署与验证效果。完成环境准备、依赖安装和参数配置后，可在Quectel Pi H1智能主控板上运行项目，实现人脸变换效果并输出结果。

当前支持的核心功能：

人脸年龄变换：生成不同年龄段的人脸效果，并合成视频播放；
人像动漫化：将人像转换为动漫风格图片；
人脸性别转换：上传一张人脸图片，基于人脸编辑与生成算法，输出一张人脸性别转换的图片。

此外，该项目支持自动识别及调用摄像头设备，同时输出运行状态与日志信息，便于用户查看运行进度及排查问题。

../../../_images/image_Xac5bvsjQoZP2PxsnqMc1iVUndb.webp

开发资源汇总¶

开发配件清单¶

配件名称	数量	规格参数
Quectel Pi H1智能主控板	1	Quectel Pi H1智能主控板
OV5693 USB摄像头模组	1	OV5693 USB摄像头模组
2PIN PH1.25接口喇叭	1	2030腔体喇叭；8Ω 2W；方形喇叭；高音质小体积扬声器；2PIN PH1.25接口
USB-C电源适配器	1	27W USB Type-C接口充电器1.2米线长中规电源PD电源适用于树莓派5代
CPU散热风扇（可选）	1	树莓派5代官方原装散热器带导热贴
Micro HDMI线	1	HDMI 2.0；线长：1 米；接口：HDMI-A（公头）转HDMI-D（公头）
网线	1	线长：1 米；传输速率：千兆
显示屏	1	HDMI显示器

配件实物参考¶

../../../_images/image_STljb00tRoG4XYx1cWjc9kTHnBg.webp

快速上手¶

开发准备¶

Quectel Pi H1出厂预装Debian 13操作系统，通常无需重新烧录系统镜像。按照以下步骤操作即可：

硬件连接¶

按照以下步骤完成所有硬件连接（步骤编号与接口示意图中的标注一致）：

../../../_images/image_OJZsb7uI9odYdOxXuBDcHxNJnHf.webp

显示连接：将Micro HDMI线的Micro HDMI端连接到智能主控板的Micro HDMI接口，另一端连接到显示器的HDMI接口。
网络连接：确保路由器已接入互联网。将网线的一端连接到智能主控板的千兆以太网端口，另一端连接到路由器的以太网端口。
输入设备连接：将USB键盘、鼠标和OV5693摄像头模组等输入设备连接到智能主控板的USB接口。如果使用无线输入设备，将无线接收器连接到扩展坞的USB接口即可。
供电连接：将USB-A电源线的USB-A端连接到电源适配器的输出端，将USB-C端连接到智能主控板的电源输入接口（通常标注为 POWER IN）。
散热风扇连接：先将散热风扇的排线插入智能主控板的FAN插槽中，再将散热器两端固定在主控板预留插孔中。

连接完成示意图¶

硬件全部连接完成后，参考示意图如下：

../../../_images/image_T9SObCx0roBAekxv4yVcqFV1n1b.webp

环境准备¶

更新软件包列表¶

执行以下命令更新软件包列表：

sudo apt update

安装系统依赖¶

安装基础依赖包：

sudo apt install -y python3 python3-venv python3-pip ffmpeg git 

安装图形界面相关依赖：

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
cd demo-face-transform

升级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。

运行程序¶

在确保已激活Python虚拟环境并完成密钥配置后，进入脚本目录赋予执行权限并启动程序：

cd demo-face-transform/src
chmod +x start.sh
./start.sh

图形界面远程运行配置¶

若需通过SSH远程会话运行图形界面程序，请完成以下配置：

在设备本地桌面终端中执行权限配置命令：

xhost +SI:localuser:pi

该命令允许本地 pi 用户访问当前X11显示服务。

在SSH远程会话中设置图形显示环境变量（SSH以 pi 用户登录为例）：

export DISPLAY=:0
export XAUTHORITY=/home/pi/.Xauthority

配置完成后，可在SSH会话中运行图形界面程序。

应用演示¶

face_transform

技术支持与贡献¶

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

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

欢迎提交Issue反馈问题，或提交Pull Request改进代码。