eos：一个基于现代 C++11/14 的轻量级、仅包含头文件的 3D 可变形人脸模型拟合库。

eos 是一个轻量级的 3D 可变形人脸模型拟合库，提供了使用人脸模型的基本功能，以及相机和形状的拟合功能。它采用现代 C++11/14 编写。

目前，eos 主要提供以下功能：

• MorphableModel 和 PcaModel 类用于表示 3DMMs，并支持基本操作如 draw_sample()。开箱即用地支持萨里人脸模型 (SFM)、4D 人脸模型 (4DFM)、巴塞尔人脸模型 (BFM) 2009 和 2017 版，以及利物浦-约克头部模型 (LYHM)。
• 低分辨率、仅包含形状信息的萨里人脸模型（share/sfm_shape_3448.bin）。
• 快速的线性姿态、形状和表情拟合，以及边缘和轮廓拟合：
  • 线性缩放正交投影相机姿态估计。
  • 线性形状到关键点的拟合，实现 O. Aldrian & W. Smith 在 PAMI 2013 中提出的“使用 3D 可变形模型进行人脸逆向渲染”方法。
  • 表情拟合，使用 SFM 的 6 种线性表情混合形状：愤怒、厌恶、恐惧、快乐、悲伤、惊讶。
  • 边缘拟合，深受 A. Bas 等人在 ACCVW 2016 中发表的“将 3D 可变形模型拟合到边缘：硬对应与软对应的比较”启发。
• 纹理提取，以获得与姿态无关的人脸纹理表示。
• Python 绑定：eos 的许多功能都可以通过 Python 模块使用（尝试运行 pip install eos-py！）。
• （实验性）：使用 Ceres 库实现非线性拟合代价函数，用于形状、相机、混合形状和颜色模型（需要单独安装 Ceres）。

一个用于可视化 3D 可变形模型和混合形状的实验性模型查看器可在 这里 获取。

使用方法

• 已在以下编译器上测试过：>=gcc-6、>=clang-5、>=Visual Studio 2017 15.5、>=Xcode 9.2。
• 该库及其 Python 绑定 无需任何外部依赖。示例应用程序需要 Boost（>=1.71.0）和 OpenCV（>=2.4.3）。

要在您自己的项目中使用该库，只需将以下目录添加到您的包含路径中：

• eos/include
• eos/3rdparty/cereal/include
• eos/3rdparty/nanoflann/include
• eos/3rdparty/eigen/Eigen
• eos/3rdparty/eigen3-nnls/src
• eos/3rdparty/toml11

请务必使用 --recursive 选项克隆，以下载所需的子模块！

构建示例和测试

• 示例应用程序所需的依赖项：CMake（>=3.8.2，或 >=3.10.0 用于 MSVC）、Boost system、filesystem、program_options（>=1.71.0）、OpenCV core、imgproc、highgui（>=2.4.3）。

构建步骤如下：

git clone --recursive https://github.com/patrikhuber/eos.git
mkdir build && cd build # 在 'eos' 文件夹旁边创建一个构建目录
cmake -G "<your favourite generator>" ../eos -DCMAKE_INSTALL_PREFIX=../install/
make && make install # 或者打开项目文件并在 Visual Studio 等 IDE 中构建

强烈建议在 Windows 上使用 vcpkg 来安装依赖项。

希望手动管理依赖项的用户可以将 initial_cache.cmake.template 复制到 initial_cache.cmake，编辑必要的路径，然后使用 -C ../eos/initial_cache.cmake 运行 cmake。在 Linux 上，您可能还需要适当地设置 -DCMAKE_BUILD_TYPE=...。

示例代码

fit-model 示例应用程序会从一张 2D 图像生成一个 3D 人脸。

在执行 make install 或运行 INSTALL 目标后，可以在 install/bin/data/ 中找到带有关键点的示例图像。模型和所需的关键点映射文件会被安装到 install/share/。

只需运行以下命令即可运行示例：

fit-model

它会从 ../share/ 目录加载人脸模型、关键点到顶点的映射、混合形状以及其他必要文件，并在示例图像上运行。您也可以通过为图像指定 -i 参数，为 ibug 关键点集指定 -l 参数来运行其他图像。完整的参数列表可以通过运行 fit-model --help 查看。

如果您刚开始使用，也建议查看 fit-model-simple，因为它所需的输入少得多，只拟合姿态和形状，不涉及混合形状或边缘拟合。其完整参数列表如下：

fit-model-simple -m ../share/sfm_shape_3448.bin -p ../share/ibug_to_sfm.txt -i data/image_0010.png -l data/image_0010.pts

两种情况下输出的都是包含形状的 obj 文件和包含提取纹理贴图的 png 文件。估计的姿态角度和形状系数可通过 API 在代码中获取。

完整代码请参阅 examples/fit-model.cpp。

萨里人脸模型

该库包含萨里可变形人脸模型的低分辨率仅形状版本。它是基于 3D 人脸扫描构建的形状变化 PCA 模型，并附带 UV 坐标以便进行纹理重映射。

完整模型可在 http://www.cvssp.org/facemodel 上找到。

4D 人脸模型 (4DFM)

eos 可用于加载、使用并进行基础拟合的 4D 人脸模型 (4DFM)，该模型由 4dface Ltd 提供。该模型具有 39 种表情/动作单元，并表现出多样化的人格特征差异。

有关该模型的更多信息，请访问 www.4dface.io/4dfm。

Python 绑定

eos 为其部分功能提供了 Python 绑定（未来还可继续扩展）。可以通过 PyPI 使用 pip install eos-py 进行安装。不过，您仍然需要从本仓库获取数据文件。

请确保在 Linux 系统上默认编译器版本为 >=gcc-7 或 >=clang-5（例如来自 ubuntu-toolchain-r/test 仓库），或者执行 CC=`which gcc-7` CXX=`which g++-7` pip install eos-py。此外，请确保您的 PATH 中包含 >=cmake-3.8.2（若使用 MSVC，则需 >=cmake-3.10.0）。

如遇问题，也可手动构建绑定：克隆仓库，在运行 cmake 时设置 -DEOS_GENERATE_PYTHON_BINDINGS=on（如果未自动找到 Python 解释器，可选择性地设置 PYTHON_EXECUTABLE 指向您的 Python 解释器）。

成功获取绑定后，即可像使用任何 Python 模块一样使用它们：

import eos
import numpy as np

model = eos.morphablemodel.load_model("eos/share/sfm_shape_3448.bin")
sample = model.get_shape_model().draw_sample([1.0, -0.5, 0.7])

help(eos) # 查看文档

有关如何运行拟合的示例，请参阅 demo.py。

Matlab 绑定

实验性（目前未维护）: eos 提供了 fit_shape_and_pose(...) 函数的 Matlab 绑定，这意味着可以在 Matlab 中运行拟合。在运行 cmake 时设置 -DEOS_GENERATE_MATLAB_BINDINGS=on 以构建所需的 mex 文件，并运行 INSTALL 目标完成安装。（如果未自动找到 Matlab 目录，请设置 Matlab_ROOT_DIR 指向您的 Matlab 安装目录）。未来可能会添加更多绑定（例如 MorphableModel 本身）。

进入 install/eos/matlab 目录并运行 demo.m，即可了解如何运行拟合。结果将生成网格和渲染参数（姿态）。

文档

Doxygen：http://patrikhuber.github.io/eos/doc/

Doxygen 中的 fit-model 示例以及 命名空间列表是入门的好起点。

许可与贡献

本代码采用 Apache License, Version 2.0 许可协议。位于 share/sfm_shape_3448.bin 的 3D 可变形人脸模型可供非商业用途免费使用。如需用于商业目的或获取其他分辨率的模型，请访问 http://www.cvssp.org/facemodel。

我们非常欢迎各类贡献！（最佳方式是通过 Pull Request 提交）。如有任何 bug 报告、建议或讨论，请使用 GitHub Issues。

如果您在自己的工作中使用了本代码，请引用以下论文：A Multiresolution 3D Morphable Face Model and Fitting Framework，P. Huber, G. Hu, R. Tena, P. Mortazavian, W. Koppen, W. Christmas, M. Rätsch, J. Kittler，2016 年国际计算机视觉理论与应用会议 (VISAPP)，意大利罗马 [PDF]。

EOS 快速上手指南

EOS 是一个轻量级的纯头文件 3D 可变形人脸模型（3DMM）拟合库，基于现代 C++11/14 编写。它支持多种主流人脸模型（如 SFM, BFM, 4DFM），提供快速的姿态、形状及表情拟合功能，并包含 Python 绑定。

环境准备

系统要求

• 编译器: GCC >= 6, Clang >= 5, Visual Studio 2017 (15.5+), 或 Xcode 9.2+。
• 构建工具: CMake >= 3.8.2 (MSVC 需 >= 3.10.0)。
• 操作系统: Linux, macOS, Windows。

依赖说明

• 核心库与 Python 绑定: 无需任何外部依赖。
• 示例程序与测试: 需要以下库（仅用于运行示例，非核心库必需）：
  • Boost (system, filesystem, program_options) >= 1.71.0
  • OpenCV (core, imgproc, highgui) >= 2.4.3
• Python 环境: 若使用 Python 绑定，需确保默认编译器为 GCC >= 7 或 Clang >= 5。

提示: Windows 用户强烈推荐使用 vcpkg 安装 Boost 和 OpenCV 依赖。

安装步骤

1. 克隆仓库

务必使用 --recursive 参数以下载必要的子模块（如 Eigen, cereal 等）。

git clone --recursive https://github.com/patrikhuber/eos.git

2. 编译与安装

创建构建目录并执行 CMake 配置。

mkdir build && cd build
cmake -G "<your favourite generator>" ../eos -DCMAKE_INSTALL_PREFIX=../install/
make && make install
# Windows 用户可在此步打开生成的解决方案文件并在 Visual Studio 中构建

• 依赖管理提示: 如果手动管理依赖路径，可复制 initial_cache.cmake.template 为 initial_cache.cmake，修改路径后通过 -C ../eos/initial_cache.cmake 传递给 cmake。
• Linux 构建类型: 建议添加 -DCMAKE_BUILD_TYPE=Release 以优化性能。

3. 安装 Python 绑定 (可选)

可以直接通过 PyPI 安装，但需确保系统满足编译器要求。

pip install eos-py

若自动安装失败，可手动从源码构建：

cd eos
mkdir build && cd build
cmake -DEOS_GENERATE_PYTHON_BINDINGS=on ..
make && make install

注意：使用 Python 绑定时，仍需从本仓库获取数据文件（位于 share/ 目录）。

基本使用

方式一：运行示例程序 (C++)

安装完成后，示例数据和模型位于 install/bin/data/ 和 install/share/。

简单模式 (仅拟合姿态和形状):

fit-model-simple -m ../share/sfm_shape_3448.bin -p ../share/ibug_to_sfm.txt -i data/image_0010.png -l data/image_0010.pts

完整模式 (包含表情混合形变和边缘拟合):

fit-model -i data/image_0010.png -l data/image_0010.pts

• 输出: 生成 .obj 格式的 3D 形状文件和 .png 格式的纹理贴图。
• 参数查看: 运行 fit-model --help 查看所有可用参数。

方式二：Python 调用

安装 eos-py 并确保能访问到模型文件（如 sfm_shape_3448.bin）。

import eos
import numpy as np

# 加载模型 (路径需指向实际文件位置)
model = eos.morphablemodel.load_model("eos/share/sfm_shape_3448.bin")

# 生成一个随机样本
sample = model.get_shape_model().draw_sample([1.0, -0.5, 0.7])

# 查看文档
help(eos)

更多详细代码示例请参考仓库中的 examples/fit-model.cpp 或 python/demo.py。