Patrik Huber 8196a74659 Added on: workflow_dispatch to manually trigger build_wheels workflow 5 months ago
.github 8196a74659 Added on: workflow_dispatch to manually trigger build_wheels workflow 5 months ago
.natvis 622fc35a0e Set channel type to RGB(A) for 3 & 4 channel images in natvis Image visualiser 4 years ago
3rdparty b4f89ce2db Updated pybind11 submodule to v2.10.4 6 months ago
doc 9816fb40be Updated namespaces.doxygen 5 years ago
examples 3fdfe4be02 Replaced glm with Eigen in multi-image fitting & app 6 months ago
include 04ce107f0f Minor documentation fix 6 months ago
matlab c3a6f700e2 Add missing parameter of MorphableModel initialization in Matlab bindings (#231) 4 years ago
python 4baa106080 Updated ScaledOrthoProjectionParameters Python bindings 6 months ago
share e5c9e4e1aa Updated comments in convert-bfm* scripts 1 year ago
utils c6fe2c7aa9 Set Boost_NO_WARN_NEW_VERSIONS to suppress CMake warning 7 months ago
.clang-format 89d421ad59 clang-format: Only allow single-line functions when they're empty 5 years ago
.gitattributes af201a8821 Initial commit 8 years ago
.gitignore 1ede3b799e Added .vs/ and out/build/ to .gitignore 1 year ago
.gitmodules 9ab85309a6 Removed GLM from CMakeLists & removed GLM submodule 6 months ago
CITATION.cff 27db304fdc Bumped version to 1.4.0 6 months ago
CMakeLists.txt 27db304fdc Bumped version to 1.4.0 6 months ago
LICENSE af201a8821 Initial commit 8 years ago
MANIFEST.in 7449058dd1 Removed glm directory from MANIFEST.in and excluded out/ directory 6 months ago
README.md 17eeea180f Added GitHub Actions build badge to readme, removed Travis & AppVeyor badges 5 months ago
initial_cache.cmake.template 940a1a38a8 Updated initial_cache.cmake.template 5 years ago
setup.py aebb00bd0d Change setup.py to use VS2022 instead of 2019 and update version to 1.4.0.post0 6 months ago
vcpkg.json 1ffe4defad Added $schema to vcpkg.json 5 months ago


eos: A lightweight header-only 3D Morphable Face Model fitting library in modern C++11/14.

Latest release Build status of master branch Apache License 2.0 Sponsor eos on GitHub Sponsors

eos is a lightweight 3D Morphable Face Model fitting library that provides basic functionality to use face models, as well as camera and shape fitting functionality. It's written in modern C++11/14.

At the moment, it mainly provides the following functionality:

  • MorphableModel and PcaModel classes to represent 3DMMs, with basic operations like draw_sample(). Supports the Surrey Face Model (SFM), 4D Face Model (4DFM), Basel Face Model (BFM) 2009 and 2017, and the Liverpool-York Head Model (LYHM) out-of-the-box
  • The low-resolution, shape-only Surrey Face Model (share/sfm_shape_3448.bin)
  • Fast, linear pose, shape and expression fitting, edge and contour fitting:
    • Linear scaled orthographic projection camera pose estimation
    • Linear shape-to-landmarks fitting, implementation of O. Aldrian & W. Smith, Inverse Rendering of Faces with a 3D Morphable Model, PAMI 2013
    • Expression fitting, with 6 linear expression blendshapes of the SFM: anger, disgust, fear, happiness, sadness, surprise
    • Edge-fitting, heavily inspired by: A. Bas et al., Fitting a 3D Morphable Model to Edges: A Comparison Between Hard and Soft Correspondences, ACCVW 2016
  • Texture extraction to obtain a pose-invariant representation of the face texture
  • Python bindings: Much of eos's functionality is available as a python module (try pip install eos-py!)
  • (Experimental): Non-linear fitting cost functions using Ceres for shape, camera, blendshapes and the colour model (needs Ceres to be installed separately)

An experimental model viewer to visualise 3D Morphable Models and blendshapes is available here.


  • Tested with the following compilers: >=gcc-6, >=clang-5, >=Visual Studio 2017 15.5, >=Xcode 9.2.
  • The library and python bindings do not require any external dependencies. The example applications require Boost (>=1.71.0) and OpenCV (>=2.4.3).

To use the library in your own project, just add the following directories to your include path:

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

Make sure to clone with --recursive to download the required submodules!

Build the examples and tests

  • Needed dependencies for the example app: CMake (>=3.8.2, or >=3.10.0 for MSVC), Boost system, filesystem, program_options (>=1.71.0), OpenCV core, imgproc, highgui (>=2.4.3).

To build:

git clone --recursive https://github.com/patrikhuber/eos.git
mkdir build && cd build # creates a build directory next to the 'eos' folder
cmake -G "<your favourite generator>" ../eos -DCMAKE_INSTALL_PREFIX=../install/
make && make install # or open the project file and build in an IDE like Visual Studio

It is strongly recommended to use vcpkg to install the dependencies on Windows. Users who wish to manage dependencies manually may find it helpful to copy initial_cache.cmake.template to initial_cache.cmake, edit the necessary paths and run cmake with -C ../eos/initial_cache.cmake. On Linux, you may also want to set -DCMAKE_BUILD_TYPE=... appropriately.

Sample code

The fit-model example app creates a 3D face from a 2D image.

After make install or running the INSTALL target, an example image with landmarks can be found in install/bin/data/. The model and the necessary landmarks mapping file are installed to install/share/.

You can run the example just by running:


It will load the face model, landmark-to-vertex mappings, blendshapes, and other required files from the ../share/ directory, and run on the example image. It can be run on other images by giving it a -i parameter for the image and -l for a set of ibug landmarks. The full set of parameters can be viewed by running fit-model --help.

If you are just getting started, it is recommended to have a look at fit-model-simple too, as it requires much fewer input, and only fits pose and shape, without any blendshapes or edge-fitting. Its full set of arguments is:

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

The output in both cases is an obj file with the shape and a png with the extracted texture map. The estimated pose angles and shape coefficients are available in the code via the API.

See examples/fit-model.cpp for the full code.

The Surrey Face Model

The library includes a low-resolution shape-only version of the Surrey Morphable Face Model. It is a PCA model of shape variation built from 3D face scans. It comes with uv-coordinates to perform texture remapping.

Surrey Face Model shape picture

The full model is available at http://www.cvssp.org/facemodel.

4D Face Model (4DFM)

eos can be used to load, use and do basic fitting with the 4D Face Model (4DFM) from 4dface Ltd. The model features 39 expressions/action units, and diverse identity variation.

4D Face Model colour picture

4D Face Model shape picture

More information about the model can be found on www.4dface.io/4dfm.

Python bindings

eos includes python bindings for some of its functionality (and more can be added!). It can be installed from PyPI with pip install eos-py. You will still need the data files from this repository. Make sure that you've got >=gcc-7 or >=clang-5 as the default compiler on Linux (for example from the ubuntu-toolchain-r/test repository) or do CC=`which gcc-7` CXX=`which g++-7` pip install eos-py. Also make sure you've got >=cmake-3.8.2 (or >=cmake-3.10.0 for MSVC) in your path. In case of issues, the bindings can also be built manually: Clone the repository and set -DEOS_GENERATE_PYTHON_BINDINGS=on when running cmake (and optionally set PYTHON_EXECUTABLE to point to your python interpreter if it's not found automatically).

After having obtained the bindings, they can be used like any python module:

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) # check the documentation

See demo.py for an example on how to run the fitting.

Matlab bindings

Experimental (not maintained currently): eos includes Matlab bindings for the fit_shape_and_pose(...) function, which means the fitting can be run from Matlab. Set -DEOS_GENERATE_MATLAB_BINDINGS=on when running cmake to build the required mex-file and run the INSTALL target to install everything. (Set Matlab_ROOT_DIR to point to your Matlab directory if it's not found automatically). More bindings (e.g. the MorphableModel itself) might be added in the future.

Go to the install/eos/matlab directory and run demo.m to see how to run the fitting. The result is a mesh and rendering parameters (pose).


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

The fit-model example and the Namespace List in doxygen are a good place to start.

License & contributions

This code is licensed under the Apache License, Version 2.0. The 3D morphable face model under share/sfm_shape_3448.bin is free for use for non-commercial purposes. For commercial purposes and to obtain other model resolutions, see http://www.cvssp.org/facemodel.

Contributions are very welcome! (best in the form of pull requests.) Please use GitHub issues for any bug reports, ideas, and discussions.

If you use this code in your own work, please cite the following paper: 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, International Conference on Computer Vision Theory and Applications (VISAPP) 2016, Rome, Italy [PDF].