Commit 406e9d8b authored by Patrik Huber's avatar Patrik Huber

Updated README

- Added expression fitting
- Added Surrey Face Model section
- Slightly restructured build and sample section
- Replaced ICIP with the VISAPP publication
- Replaced license badge with static one
parent 9cba840f
# eos: A lightweight header-only 3D Morphable Face Model fitting library in modern C++11/14. # eos: A lightweight header-only 3D Morphable Face Model fitting library in modern C++11/14.
[![GitHub release](http://img.shields.io/github/release/patrikhuber/eos.svg?style=flat-square)][release] [![GitHub release](http://img.shields.io/github/release/patrikhuber/eos.svg?style=flat-square)][release]
[![Apache License 2.0](https://img.shields.io/github/license/patrikhuber/eos.svg?style=flat-square)][license] [![Apache License 2.0](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat-square)][license]
[release]: https://github.com/patrikhuber/eos/releases [release]: https://github.com/patrikhuber/eos/releases
[license]: https://github.com/patrikhuber/eos/blob/master/LICENSE [license]: https://github.com/patrikhuber/eos/blob/master/LICENSE
eos is a tiny 3D Morphable Face Model fitting library that provides just the bare minimum to load a model and perform camera and shape fitting. It's written in modern C++11/14. eos is a lightweight 3D Morphable Face Model fitting library that provides just the bare minimum to load a model and perform camera and shape fitting. It's written in modern C++11/14.
At the moment, it mainly provides the following functionality: At the moment, it mainly provides the following functionality:
* MorphableModel class to represent a 3DMM (using OpenCVs `cv::Mat`) * MorphableModel class to represent a 3DMM (using OpenCVs `cv::Mat`)
* Our low-resolution, shape-only 3D Morphable Face Model ([share/sfm_shape_3448.bin](https://github.com/patrikhuber/eos/blob/master/share/sfm_shape_3448.bin))
* Camera pose estimation, implementation of: * Camera pose estimation, implementation of:
* the _Gold Standard Algorithm_ for estimating an affine camera matrix, from Multiple View Geometry, Hartley & Zisserman * the _Gold Standard Algorithm_ for estimating an affine camera matrix, from Multiple View Geometry, Hartley & Zisserman
* a non-linear algorithm that directly estimates the pose angles and camera translation * a non-linear algorithm that directly estimates the pose angles and camera translation
* Shape fitting, implementation of the linear shape-to-landmarks fitting of O. Aldrian & W. Smith, _Inverse Rendering of Faces with a 3D Morphable Model_, PAMI 2013 * Shape fitting, implementation of the linear shape-to-landmarks fitting of O. Aldrian & W. Smith, _Inverse Rendering of Faces with a 3D Morphable Model_, PAMI 2013
* Expression fitting, and 6 linear expression blendshapes: angry, disgust, fear, happy, sad, surprised.
* Isomap texture extraction to obtain a pose-invariant representation of the face texture. * Isomap texture extraction to obtain a pose-invariant representation of the face texture.
## Usage ## Usage
...@@ -33,15 +35,18 @@ To use the library in your own project, just add the following directories to yo ...@@ -33,15 +35,18 @@ To use the library in your own project, just add the following directories to yo
To build: To build:
* copy `initial_cache.cmake.template` to `initial_cache.cmake`, edit the necessary paths ```
* create a build directory next to the `eos` folder: `mkdir build; cd build` git clone git@github.com:patrikhuber/eos.git
* `cmake -C ../eos/initial_cache.cmake -G "<your favourite generator>" ../eos -DCMAKE_INSTALL_PREFIX=../install/` mkdir build && cd build # creates a build directory next to the _eos_ folder
* build using your favourite tools, e.g. `make; make install` or open the solution in Visual Studio. 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
```
If some dependencies can't be found, copy `initial_cache.cmake.template` to `initial_cache.cmake`, edit the necessary paths and run `cmake` with `-C ../eos/initial_cache.cmake`.
## Sample code ## Sample code
See [examples/fit-model.cpp](https://github.com/patrikhuber/eos/blob/master/examples/fit-model.cpp). 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/`. 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/`.
...@@ -49,12 +54,22 @@ You can run the example just by running: ...@@ -49,12 +54,22 @@ You can run the example just by running:
`fit-model` `fit-model`
Or, by manually specifying the face model, landmark vertex mappings, an image and its 2D landmarks: Or, by manually specifying the face model, landmark-to-vertex mappings, an image and its 2D landmarks:
`fit-model -m ../share/sfm_shape_3448.bin -p ../share/ibug2did.txt -i data/image_0010.png -l data/image_0010.pts` `fit-model -m ../share/sfm_shape_3448.bin -p ../share/ibug2did.txt -i data/image_0010.png -l data/image_0010.pts`
The output is an `obj` file with the shape and a `png` with the extracted isomap. The estimated pose angles and shape coefficients are available in the code via the API. The output is an `obj` file with the shape and a `png` with the extracted isomap. The estimated pose angles and shape coefficients are available in the code via the API.
See [examples/fit-model.cpp](https://github.com/patrikhuber/eos/blob/master/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.
<img src="https://raw.githubusercontent.com/patrikhuber/eos/gh-pages/images/sfm_shape_3448_mesh.png" width=20% alt="Face Model Picture"></img>
The full model will be available soon too via academic licencing.
## Documentation ## Documentation
Doxygen: http://patrikhuber.github.io/eos/doc/ Doxygen: http://patrikhuber.github.io/eos/doc/
...@@ -68,4 +83,4 @@ This code is licensed under the Apache License, Version 2.0. The 3D morphable fa ...@@ -68,4 +83,4 @@ This code is licensed under the Apache License, Version 2.0. The 3D morphable fa
Contributions are very welcome! (best in the form of pull requests.) Please use Github issues for any bug reports, ideas, and discussions. 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: _Fitting 3D Morphable Models using Local Features_, P. Huber, Z. Feng, W. Christmas, J. Kittler, M. Rätsch, IEEE International Conference on Image Processing (ICIP) 2015, Québec City, Canada (http://arxiv.org/abs/1503.02330). 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]](http://www.patrikhuber.ch/files/3DMM_Framework_VISAPP_2016.pdf).
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment