FLAME: Learning a model of facial shape and expression from 4D scans（SIGGRAPH2017）环境配置与集成扩展示例

关于 FLAME 项目

FLAME（Faces Learned with an Articulated Model and Expressions）是一种面向3D人脸建模的低维高表现力模型，旨在填补高端与低端3D人脸建模方法之间的空白。

FLAME 基于3800个高精度对齐的3D扫描数据，构建了线性形状空间，并结合了下颚、颈部、眼球的关节动作，姿态相关校正形变，以及全局表情形变。模型还利用 D3DFACS 数据集的4D面部序列进行训练，总计基于超过33,000次扫描。FLAME 兼具高表现力与易用性，能够与现有图形软件兼容，且适用于静态3D扫描与动态4D序列的拟合实验。研究表明，FLAME 在拟合精度上显著优于 FaceWarehouse 和 Basel Face Model，目前已开放用于研究用途。

项目的主要资源和相关信息如下：

项目主页：Flame
Github：FLAME-Universe
Github：FLAME_PyTorch（本文复现）

本文将介绍笔者在自己环境下对 FLAME_PyTorch 项目的复现及环境配置方法。

环境配置

系统环境

系统版本：笔者使用 Windows 11 + Anaconda 环境

FLAME_PyTorch 的 Python (Conda) 环境

进入 FLAME_PyTorch 项目的目录：
```
.cd <FLAME_PyTorch 项目路径>
```

配置 Conda 的清华源以加快镜像下载（可跳过）：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main

创建并激活 FLAME_PyTorch 的 Conda 环境：

conda create -n flame-pytorch-env python=3.8
conda activate flame-pytorch-env

配置 pip 的清华源（可跳过）：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

安装 FLAME_PyTorch 所需的依赖：
```
pip install -r requirements.txt
```

模型准备

在 FLAME_PyTorch 项目目录下的 /model 文件夹（不存在则创建）中放置以下模型文件：

FLAME2020 模型：下载，解压得到三个 pkl 文件，并放置到 /model 目录
- Flame-Downloads
- 文件包括：
  - generic_model.pkl
  - male_model.pkl（项目基本配置未用到，可自行添加）
  - female_model.pkl（项目基本配置未用到，可自行添加）
Landmark embedings from RingNet Project：下载，在 /flame_model 目录中找到如下两个文件，并直接放置到 /model 目录
- RingNet
- 文件包括：
  - flame_static_embedding.pkl
  - flame_dynamic_embedding.npy

测试配置环境

Demo 测试运行

在 DECA 项目目录下，运行以下命令以测试 DECA 的重建功能

python main.py

常见问题及可能解决方案

1. _pickle.UnpicklingError: the STRING opcode argument must be quoted

报错信息：

Traceback (most recent call last):
  File "<你的 FLAME_PyTorch 项目路径>\FLAME_PyTorch\main.py", line 31, in <module>
    flamelayer = FLAME(config)
  File "<你的 FLAME_PyTorch 项目路径>\FLAME_PyTorch\flame_pytorch\flame.py", line 139, in __init__
    static_embeddings = Struct(**pickle.load(f, encoding="latin1"))
_pickle.UnpicklingError: the STRING opcode argument must be quoted

报错分析：

该错误通常发生在 Python 使用 pickle.load 解析 .pkl 文件时，具体原因是 .pkl 文件中的换行符格式不兼容：
Windows 环境中的换行符为 \r\n（CRLF），Unix/Linux 环境中的换行符为 \n（LF）。
Python 的某些版本（如 3.4 及更高版本）在使用 C 编写的 pickle 解析器时，无法解析包含 DOS 格式换行符的 .pkl 文件。
一些版本的 Git 在处理文件时可能会将 Unix 格式的换行符自动转换为 DOS 格式，从而导致该问题。

解决方案：

通过将文件的换行符从 DOS 格式 (\r\n) 转换为 Unix 格式 (\n)，可以解决该问题。以下是 Python 脚本的实现代码：

# dos2unix.py
import argparse

def convert_dos2unix(input_file, output_file):
    """
    Convert DOS linefeeds (CRLF) to Unix linefeeds (LF).
    """
    content = ''
    outsize = 0
    with open(input_file, 'rb') as infile:
        content = infile.read()
    with open(output_file, 'wb') as output:
        for line in content.splitlines():
            outsize += len(line) + 1
            output.write(line + b'\n')
    print("Done. Saved %s bytes." % (len(content) - outsize))

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Convert DOS linefeeds (CRLF) to Unix linefeeds (LF).")
    parser.add_argument('-i', '--input', required=True, help="Path to the input file (source).")
    parser.add_argument('-o', '--output', required=True, help="Path to the output file (destination).")

    args = parser.parse_args()
    convert_dos2unix(args.input, args.output)

将脚本保存为 dos2unix.py。
在命令行中运行以下命令，将目标 .pkl 文件从 DOS 换行格式转换为 Unix 换行格式：
python dos2unix.py -i model/flame_static_embedding_win.pkl -o model/flame_static_embedding.pkl
再次运行程序，确保 .pkl 文件已被正确解析。

2. PyTorch CUDA 不支持

报错信息：

creating the FLAME Decoder
Traceback (most recent call last):
  File "<你的 FLAME_PyTorch 项目路径>\FLAME_PyTorch\main.py", line 34, in <module>
    shape_params = torch.zeros(8, 100).cuda()
  File "<你的 Anaconda3 路径>\Anaconda3\lib\site-packages\torch\cuda\__init__.py", line 363, in _lazy_init
    raise AssertionError("Torch not compiled with CUDA enabled")
AssertionError: Torch not compiled with CUDA enabled

报错分析：

当前安装的 PyTorch 版本与 GPU 的 CUDA 版本不兼容。

解决方案：

卸载当前的 PyTorch 和 torchvision：
```
pip uninstall torch torchvision
```

安装兼容（与 CUDA 11.7 匹配）的版本：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu117

运行成功结果

在 FLAME_PyTorch 项目目录下，运行以下命令以测试 FLAME_PyTorch 的功能

python main.py

如果命令行输出类似以下内容

creating the FLAME Decoder
torch.Size([8, 5023, 3]) torch.Size([8, 68, 3])

并且弹出多视角的 Scene Viewer 程序并在窗口中能够查看具有 3D Landmarks 的 3D 模型。

恭喜你，你已经成功配置好了 FLAME_PyTorch 的运行环境。